diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c94c0683 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,27 @@ +# Contributing + +tktk + +## Pull Request Process + +tktk + +## Code of Conduct + +tktk + +## Reporting Bugs + +tktk + +## Suggesting Enhancements + +tktk + +## Your First Code Contribution + +tktk + +## Styleguides + +tktk diff --git a/docs/developer_guide/contributing_code.rst b/docs/developer_guide/contributing_code.rst new file mode 100644 index 00000000..4d0454f3 --- /dev/null +++ b/docs/developer_guide/contributing_code.rst @@ -0,0 +1,43 @@ +Contributing Code +================= + +Follow these steps to contribute code to `OneMod`: + +1. **Fork the repository (optional for core contributors)**: + Fork the `OneMod` 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 diff --git a/docs/developer_guide/contributing_docs.rst b/docs/developer_guide/contributing_docs.rst new file mode 100644 index 00000000..24987d32 --- /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 new file mode 100644 index 00000000..c1882860 --- /dev/null +++ b/docs/developer_guide/index.rst @@ -0,0 +1,22 @@ +Developer Guide +=============== + +Welcome to the `OneMod` 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. + +.. toctree:: + :hidden: + + setup + testing + contributing_code + contributing_docs + +--- + +.. admonition:: Note + :class: hint + + For getting started and local environment setup, see :ref:`Setup`. + For testing instructions, see :ref:`Running Tests`. + 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 00000000..767967fa --- /dev/null +++ b/docs/developer_guide/setup.rst @@ -0,0 +1,143 @@ +Setting Up Your Development Environment +======================================= + +Follow the steps below to set up a local development environment for `OneMod`. You can use either a Python virtual environment (`venv`) or a Conda environment, depending on your preference. The instructions below include both options. + +Before starting, ensure you have: + +- `Python` installed (see **Python Versions** below for requirements). +- `Make` installed on your system. + +--- + +1. Clone the Repository +------------------------ + +First, clone the `OneMod` repository and navigate to the project directory: + +.. code-block:: bash + + git clone https://github.com/ihmeuw-msca/onemod.git + cd onemod + +--- + +2. Check Required Python Versions +---------------------------------- + +`OneMod` requires a specific Python version to ensure compatibility. Refer to the `pyproject.toml` file for supported versions: + +.. code-block:: toml + + [project] + name = "onemod" + requires-python = ">=3.10, <3.13" + +--- + +Ensure you have a compatible Python version installed, or use `conda` to set up a new environment with the required version: + +.. code-block:: bash + + python --version + +--- + +3. Set Up the Development Environment +-------------------------------------- + +You can choose between a **virtual environment (venv)** or a **Conda environment** to set up your development environment. + +**Option 1: Using Virtual Environment (venv)** + +Run the following commands to set up the virtual environment: + +.. code-block:: bash + + make setup ENV_TYPE=venv PYTHON_VERSION=3.10 + +This will: +- Create a virtual environment in the `.venv` directory. +- Install the required dependencies (including development tools). + +Activate the environment: + +.. code-block:: bash + + source .venv/bin/activate # On Windows, use `.venv\Scripts\activate` + +**Option 2: Using Conda** + +Run the following commands to set up a Conda environment: + +.. code-block:: bash + + make setup ENV_TYPE=conda CONDA_ENV=onemod PYTHON_VERSION=3.10 + +This will: +- Create a Conda environment named `onemod` (or supply custom name of your choice). +- Install the required dependencies (including development tools). + +Activate the Conda environment: + +.. code-block:: bash + + conda activate onemod + +--- + +4. Verify the Setup +------------------- + +After setting up the environment, verify that everything works as expected: + +.. code-block:: bash + + make list-vars + +This will display the current values of key environment variables, including `ENV_TYPE`, `PYTHON_VERSION`, and `CONDA_ENV`. + +To confirm that `pre-commit` hooks and tools (e.g., `mypy`, `ruff`) are working, run: + +.. code-block:: bash + + pre-commit run --all-files + +--- + +5. Start Developing! +-------------------- + +Congratulations! You’re ready to start contributing to `OneMod`. + +To manually run development tools, you can use the `Makefile` shortcuts: + +- **Run `mypy` for type checking**: + .. code-block:: bash + + make mypy + +- **Clean up the environment**: + .. code-block:: bash + + make clean + +For details on testing, contributing, or other development workflows, see the corresponding sections in the documentation: + +- **Testing**: :ref:`Running Tests` +- **Contributing Code**: :ref:`Contributing Code` +- **Contributing Documentation**: :ref:`Contributing to Documentation` + +--- + +6. Notes for Contributors +------------------------- + +- **Python Versions**: Ensure you are using the correct Python version (see `pyproject.toml`). +- **Dependencies**: Dependencies are managed in `pyproject.toml`. Use `pip install -e ".[dev]"` for manual installation if needed. +- **Makefile**: Use the `Makefile` for consistent setup and tooling. +- **Pre-commit Hooks**: Pre-commit hooks (e.g., `mypy`, `ruff`) ensure code quality. They are automatically installed during setup. + +--- + +That’s it! If you encounter any issues during setup, please refer to the project's `CONTRIBUTING.md` or reach out for help. diff --git a/docs/developer_guide/testing.rst b/docs/developer_guide/testing.rst new file mode 100644 index 00000000..3fa9b368 --- /dev/null +++ b/docs/developer_guide/testing.rst @@ -0,0 +1,26 @@ +Running Tests +============= + +`OneMod` 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=onemod + +3. View detailed coverage in HTML format: + + .. code-block:: bash + + pytest --cov=onemod --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!