Writing documentation¶

Documentation for owmeta-core is housed in two locations:

In the top-level project directory as INSTALL.md and README.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. To get the sphinx-build command, install the documentation requirements with:

pip install -r doc-requirements.txt

Then, you can run sphinx-build like this:

sphinx-build -w sphinx-errors docs <build_destination>

You can also invoke the command with default arguments (i.e., with output to build/sphinx using setup.py:

python setup.py build_sphinx

The docs will be compiled to html which you can view by pointing your web browser at <build_destination>/index.html. The documentation will be rendered using the same theme as is used on the readthedocs.org site.

API Documentation¶

API documentation is generated by the Sphinx autodoc and apidoc extensions. The numpydoc format should be easy to pick up on, but a reference is available here. Just add a docstring to your function/class/method and your class should appear among the other documented classes. Note, however, that “special” methods like __call__ will not show up by default – if they need to be documented for a given class, add a declaration like this to the class documentation:

class SpecialMethodDocExample:
    '''
    Example class doc

    .. automethod:: __call__
    '''

    def __call__(self):
        '''
        Hey, I'm in the API documentation!
        '''

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.