From d4738db0abb177c4c1ee065c76b80ed3410eb8cc Mon Sep 17 00:00:00 2001 From: Wes Warriner Date: Mon, 9 Dec 2024 23:21:51 -0700 Subject: [PATCH] flatten dev optional deps list in pyproject toml; add license file ref; add initial developer guide docs --- docs/developer_guide/contributing_code.rst | 43 ++++++++++++++ docs/developer_guide/contributing_docs.rst | 26 +++++++++ docs/developer_guide/index.rst | 65 +++++++++++++++++++--- docs/developer_guide/setup.rst | 26 +++++++++ docs/developer_guide/testing.rst | 26 +++++++++ pyproject.toml | 5 +- 6 files changed, 183 insertions(+), 8 deletions(-) create mode 100644 docs/developer_guide/contributing_code.rst create mode 100644 docs/developer_guide/contributing_docs.rst create mode 100644 docs/developer_guide/setup.rst create mode 100644 docs/developer_guide/testing.rst diff --git a/docs/developer_guide/contributing_code.rst b/docs/developer_guide/contributing_code.rst new file mode 100644 index 0000000..5949ed8 --- /dev/null +++ b/docs/developer_guide/contributing_code.rst @@ -0,0 +1,43 @@ +Contributing Code +================= + +Follow these steps to contribute code to `raking`: + +1. **Fork the repository (optional for core contributors)**: + Fork the `raking` repository on GitHub to your account. + +2. **Create a branch**: + Work on your feature or fix in a new branch: + + .. code-block:: bash + + git checkout -b my-feature + +3. **Make your changes**: + Write clean, well-documented code. Add tests to verify your changes. + +4. **Run tests**: + Ensure all tests pass before pushing your code: + + .. code-block:: bash + + pytest + +5. **Submit a pull request**: + Push your branch to your forked repository and submit a pull request. + +Keeping Your Fork Updated +------------------------- +For external contributors, keep your fork updated with the main repository: + +1. Fetch the latest changes from upstream: + + .. code-block:: bash + + git fetch upstream + +2. Merge or rebase the changes into your branch: + + .. code-block:: bash + + git merge upstream/main # Or rebase: git rebase upstream/main \ No newline at end of file diff --git a/docs/developer_guide/contributing_docs.rst b/docs/developer_guide/contributing_docs.rst new file mode 100644 index 0000000..24987d3 --- /dev/null +++ b/docs/developer_guide/contributing_docs.rst @@ -0,0 +1,26 @@ +Contributing to Documentation +============================= + +To contribute to the documentation: + +1. **Install dependencies**: + Ensure you have the `docs` optional dependencies installed: + + .. code-block:: bash + + pip install -e ".[docs]" + +2. **Build the documentation locally**: + Build the HTML documentation to preview changes: + + .. code-block:: bash + + sphinx-build -b html docs docs/_build + + Open `docs/_build/index.html` in your browser to view the docs. + +3. **Update the relevant `.rst` files**: + Make your edits in the `docs/` folder. + +4. **Submit your changes**: + Follow the general contribution workflow to open a pull request with your documentation updates. diff --git a/docs/developer_guide/index.rst b/docs/developer_guide/index.rst index b0cc18e..bf2ccb4 100644 --- a/docs/developer_guide/index.rst +++ b/docs/developer_guide/index.rst @@ -1,11 +1,62 @@ -Developer guide +Developer Guide =============== -.. admonition:: Work in progress... - :class: attention +Welcome to the `raking` developer guide! This section provides instructions and tips for contributing to the package, including setting up your development environment, running tests, and updating the documentation. - Current topics +.. toctree:: + :hidden: - * briefly describe how to contribute - * contributing to the documentation - * contributing to the code base + setup + testing + contributing_code + contributing_docs + +Setting Up Your Development Environment +--------------------------------------- + +To get started with developing for `raking`, follow the instructions below to set up your local environment. + +1. **Clone the Repository**: + + Start by cloning the `raking` repository from GitHub: + + .. code-block:: bash + + git clone https://github.com/ihmeuw-msca/raking.git + cd raking + +2. **Create a Virtual Environment**: + + Create a Python virtual environment to isolate your development dependencies: + + .. code-block:: bash + + python -m venv .venv + source .venv/bin/activate # On Windows, use `.venv\Scripts\activate` + +3. **Install Development Dependencies**: + + Install the package along with the development dependencies: + + .. code-block:: bash + + pip install -e ".[dev]" + + This command installs the package in editable mode (`-e`) along with the optional `dev` dependencies. + +4. **Verify Installation**: + + Ensure the dependencies are installed correctly: + + .. code-block:: bash + + python -m pytest + sphinx-build -b html docs docs/_build + + If these commands run without errors, you’re ready to start developing! + +.. admonition:: Note + :class: hint + + For details on contributing to the codebase, see :ref:`Contributing Code`. + For documentation contributions, see :ref:`Contributing to Documentation`. diff --git a/docs/developer_guide/setup.rst b/docs/developer_guide/setup.rst new file mode 100644 index 0000000..6407b22 --- /dev/null +++ b/docs/developer_guide/setup.rst @@ -0,0 +1,26 @@ +Setting Up Your Environment +=========================== + +Follow the steps below to set up a local development environment for `raking`. + +1. Clone the repository: + + .. code-block:: bash + + git clone https://github.com/ihmeuw-msca/raking.git + cd raking + +2. Create a Python virtual environment: + + .. code-block:: bash + + python -m venv .venv + source .venv/bin/activate # On Windows, use `.venv\Scripts\activate` + +3. Install the package and development dependencies: + + .. code-block:: bash + + pip install -e ".[dev]" + +Congratulations! You’re ready to start contributing. diff --git a/docs/developer_guide/testing.rst b/docs/developer_guide/testing.rst new file mode 100644 index 0000000..bd4099e --- /dev/null +++ b/docs/developer_guide/testing.rst @@ -0,0 +1,26 @@ +Running Tests +============= + +`raking` uses `pytest` for testing. To ensure all tests pass, follow these steps: + +1. Run the test suite: + + .. code-block:: bash + + pytest + +2. Generate a test coverage report (optional): + + .. code-block:: bash + + pytest --cov=raking + +3. View detailed coverage in HTML format: + + .. code-block:: bash + + pytest --cov=raking --cov-report=html + + Open the `htmlcov/index.html` file in your browser to inspect test coverage. + +Remember to write tests for new features or bug fixes! diff --git a/pyproject.toml b/pyproject.toml index ae70611..0d46d14 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,7 +22,10 @@ dependencies = ["numpy", "pandas", "scipy"] [project.optional-dependencies] test = ["pytest", "pytest-cov"] docs = ["sphinx", "sphinx-autodoc-typehints", "furo", "ipykernel"] -dev = ["test", "docs", "pre-commit", "ruff"] +dev = ["pytest", "pytest-cov", "sphinx", "sphinx-autodoc-typehints", "furo", "ipykernel", "pre-commit", "ruff"] [project.urls] github = "https://github.com/ihmeuw-msca/raking" + +[tool.setuptools] +license-files = ["LICENSE"]