diff --git a/.github/wordlist.txt b/.github/wordlist.txt index 22ae767e46..540e915277 100644 --- a/.github/wordlist.txt +++ b/.github/wordlist.txt @@ -74,6 +74,8 @@ bysource charset del dev +docstring +docstrings eg exc firsttimersonly diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4da55c737c..d87e6ba1c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,19 @@ using `invoke standalone-tests`; similarly, RedisCluster tests can be run by usi Each run of tests starts and stops the various dockers required. Sometimes things get stuck, an `invoke clean` can help. +## Documentation + +If relevant, update the code documentation, via docstrings, or in `/docs`. + +You can check how the documentation looks locally by running `invoke build-docs` +and loading the generated HTML files in a browser. + +Historically there is a mix of styles in the docstrings, but the preferred way +of documenting code is by applying the +[Google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). +Type hints should be added according to PEP484, and should not be repeated in +the docstrings. + ### Docker Tips Following are a few tips that can help you work with the Docker-based diff --git a/docs/conf.py b/docs/conf.py index a201da2fc0..33a8589654 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,6 +10,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import datetime import os import sys @@ -30,12 +31,15 @@ "nbsphinx", "sphinx_gallery.load_style", "sphinx.ext.autodoc", - "sphinx_autodoc_typehints", - "sphinx.ext.doctest", "sphinx.ext.viewcode", "sphinx.ext.autosectionlabel", + "sphinx.ext.napoleon", ] +# Napoleon settings. We only accept Google-style docstrings. +napoleon_google_docstring = True +napoleon_numpy_docstring = False + # AutosectionLabel settings. # Uses a :