SphinxDocs

SphinxDocNotes.md

Sphinx Notes

Docs in another dir

In order to include modules from another directory, import the directory w.r.t. the 'doc' directory. E.g. if you put the docs folder in the top level directory of the project, the sphinx interpreter runs in the docs directory. Thus, to import the top level directory, import ... If you want to import a folder within the top level directory import ../<folder>.

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Then, when you want to produce documentation for a module, use python import notation if you were to import that module from the docs directory normally.

.. automodule:: <python>.<import>.<notation>
    :members:
    :undoc-members:
    :inherited-members:
    :show-inheritance:

Autodoc

Autodoc is an extension that includes a set of directives (read 'functions') that automatically generate documentation for a module, class, function etc. In rST below.

.. automodule:: <python>.<import>.<notation>
    :members:

This is convenient but you must write the .. automodule:: directive for every module manually. A convenient way to do this is to use sphinx-apidoc or the user-made better-apidoc. Both of these traverse the input directory and generate autodoc stubs for each module. better-apidoc furthermore, allows templates for the generated stubs. https://github.com/goerz/better-apidoc

rST In Docstring (parameter definitions)

There must be a blank line between the docstring comments and the parameter definitions. The parameter definitions is called field lists in sphinx. If there is no blank line, the rST will not be detected.

def my_func(cat_height, cat_weight, cat_name):
    """
    There must be a blank line between the comments and the field lists below.
    
    :param cat_height: Parameter description here
    :param cat_weight: Cat is fat
    :param cat_name: FatCat
    :return: Cat
    """