To actually read the docs, head to https://fixate.readthedocs.io.
This document is about how to add to and improve the existing docs, and the setup for building them.
See Documentation Quadrants. tl;dr - documentation falls into one of these categories, and it's good to both: 1. keep them separate and 2. ensure there is a good quantity/quality of each type
- tutorials
- how-to guides
- discussions
- reference
Currently we have the following:
- quickstart (tutorial)
- example_walkthrough (tutorial)
- example projects (how-to)
- fixate/fixate (reference in-depth API docs, see below)
- release-notes (reference)
The documentation build uses the Python-standard Sphinx, with configuration contained in docs/conf.py
.
tox -e docs
will run the docs build. See the [testenv:docs]
section in tox.ini
for configuration. Under the hood, it's essentially running fixate/docs > sphinx-build <doc_src> <doc_dest>
in a venv with the requirements from docs/requirements.
API docs are built automatically using autodoc, which pulls from the docstrings in the source.
The best "how-tos" at the moment are the example projects. Ideally these should have good explanations in their docstrings, then they can be pulled out at a higher level of the docs' table of contents.
The structure of the API reference is done separately, via sphix-apidoc which was from a manual run of:
sphinx-apidoc -o fixate --no-toc --remove-old --module-first ../src/fixate
This placed the API reference structure in the docs/fixate
subdirectory. In there, fixate.rst
has the top level, then there is a separate file for each subpackage, eg fixate.core.rst
and fixate.drivers.dmm.rst
.
I ran it with these args:
--module-first
since the modules have the more useful stuff--no-toc
don't generate modules.rst since it's a full package--remove-old
since we have source control, just delete superseded files
If the package structure changes, then the sphinx-apidocs call above will need to be re-run with -f
, which will overwrite the old files.
While the apidoc potentially could be re-run on every build, at least for now I think better to commit in the original run, and then the structure of the api reference can be tweaked to best surface the most important info.
Note: The auto-generated template has been manually modified. Re-running sphinx-apidoc in the future will need to preserve those changes, or incorporate them into the source somehow.
Autodoc originally used ReStructured Text docstring style, but the sphix.ext.napoleon extension allows Google/NumPy style.
We can mix-and-match, so we can transition from one to the other as required.
tl;dr instead of rst's:
:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage
the docstrings will look like:
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The :class:`FileStorage` instance to wrap
Returns:
BufferedFileStorage: A buffered writable file descriptor
Note improved readability. From the reference,
Google style tends to be easier to read for short and simple docstrings, whereas NumPy style tends be easier to read for long and in-depth docstrings. Note all standard reStructuredText formatting still works as expected.
For now we'll go with Google. For examples I've been using code blocks:
This is an example::
This will go into a code block in the docs.