Merge pull request #5 from ihmeuw-msca/fix/getting-started-updates

Initial Developer Guide

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

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.

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`.

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.

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!

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"]