diff --git a/docs/contributing/index.md b/docs/contributing/index.md index fc39f629..a8b9f624 100644 --- a/docs/contributing/index.md +++ b/docs/contributing/index.md @@ -19,7 +19,7 @@ Please note that we have a [code of conduct](./code-of-conduct.md). Please follo From here, you might want to fix and issue or bug, or add a new feature. Jump to the relevant section to proceed. -### ...to fix an issue or bug +### Fixing an Issue or Bug - Create a GitHub issue with a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example), @@ -33,7 +33,7 @@ relevant section to proceed. Once you've completed these steps, you are ready to submit your contribution. -### ...to contribute a new feature +### Contributing a New Feature - Create an issue and discuss the feature's scope and its fit for this package with the team - Create a branch for your new feature in your fork @@ -43,6 +43,28 @@ Once you've completed these steps, you are ready to submit your contribution. Once you've completed these steps, you are ready to submit your contribution. + +### Contributing to Documentation + +#### Documentation Style + +To ensure that our code is well-documented and easy to understand, we use [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) to document all functions, classes, and methods in this library. + +#### Locally rendering the documentation + +To work on documentation locally, we provide a script that will automatically re-render the docs when you make changes: + +``` +./scripts/docs-live.sh +``` + +If you encounter any issues while setting up the documentation using the provided steps, please refer to our [tutorial]( https://www.youtube.com/watch?v=mNjlMZ4F3So) for additional guidance. + +##### Caveats and considerations + +Our mkdocs setup has a known limitation: the hot reloader won't auto-reload when changing docstrings. To see updates, manually rebuild and re-serve docs. We're working to improve the developer experience and appreciate your patience. + + ## Submitting your contribution - Run all unit tests successfully in your branch @@ -53,18 +75,19 @@ Once you've completed these steps, you are ready to submit your contribution. ### Please format and lint as you go -```bash -make format lint -``` -We attempt to provide comprehensive type annotations within this repository. If -you do not provide fully annotated functions or methods, the `lint` command will -fail. Over time, we plan to increase type-checking strictness in order to -ensure more precise, beneficial type annotations. +#### Usage of Pre-Commit + +To maintain code quality, we use pre-commit for automated checks before committing changes. Install and configure pre-commit to ensure high-quality contributions. + +To set up pre-commit, follow these steps: + +- `pip install pre-commit` ([official installation docs](https://pre-commit.com/#install)) +- `pre-commit install` to enable it to run automatically +- `pre-commit run -a` to run it manually + -We have included type stubs for the untyped `python-cmr` library, which we -intend to eventually upstream. Since `python-cmr` exposes the `cmr` package, -the stubs appear under `stubs/cmr`. +We have included type stubs for the untyped `python-cmr` library, which we intend to eventually upstream. Since `python-cmr` exposes the `cmr` package, the stubs appear under `stubs/cmr`. ## Pull Request process