Adding documentation¶
Documentation for PyOpenWorm is housed in two locations:
- In the top-level project directory as
INSTALL.md
andREADME.md
.- As a Sphinx project under the
docs
directory
By way of example, to add a page about useful facts concerning C. elegans to
the documentation, include an entry in the list under toctree
in
docs/index.rst
like:
worm-facts
and create the file worm-facts.rst
under the docs
directory and
add a line:
.. _worm-facts:
to the top of your file, remembering to leave an empty line before adding all of your wonderful worm facts.
You can get a preview of what your documentation will look like when it is
published by running sphinx-build
on the docs directory:
sphinx-build -w sphinx-errors docs build_destination
The docs will be compiled to html which you can view by pointing your web
browser at build_destination/index.html
. If you want to view the
documentation locally with the ReadTheDocs theme you’ll need to
download and install it.
API Documentation¶
API documentation is generated by the Sphinx autodoc extension. The
format should be easy to pick up on, but a reference is available here. Just add a docstring to your function/class/method and add an
automodule
line to PyOpenWorm/__init__.py
and your class should
appear among the other documented classes.
Substitutions¶
Project-wide substitutions can be (conservatively!) added to allow for easily
changing a value over all of the documentation. Currently defined substitutions
can be found in conf.py
in the rst_epilog
setting. More about
substitutions
Conventions¶
If you’d like to add a convention, list it here and start using it. It can be reviewed as part of a pull request.
- Narrative text should be wrapped at 80 characters.
- Long links should be extracted from narrative text. Use your judgement on what ‘long’ is, but if it causes the line width to stray beyond 80 characters that’s a good indication.