Documentation of pypospack

Documentation of pyflamestk is done through a Sphinx which is a documentation generator. It takes a variety of soruce files in plain text, and generates documentation with it. It can provide a variety of documentation formats including PDF and HTML formats.

For Sphinx to find a module it must be importable. This means that the module or package must be in one of the directories on the sys.path.

Since pyflamestk adopts the google style docstrings over reStructuredText, the napoleon extention needs to be enabled as well. napoleon is a preprocessor that converts doctstrings to correct reStructuredText before autodoc processes them.

PEP 484 introduced a standard way to express types in python code. This is an alternative to expressing types directly in docstrings. PEP 484 alllows type checks and IDEs to take advantage of them for static code analysis.

An example Google style with Python 3 type annotations:

def func(arg1: int, arg2: str) -> bool: """Summary line. Extended description of function. Args: arg1: Description of arg1 arg2: Description of arg2 Returns: Description of return value """ return True

Extensions required to build pyflamestk documentation

autodoc: automatically insert docstrings from modules

pip install sphinxcontrib-napoleon

add to conf.py

extensions = ['sphinx.ext.autodoc','sphinxcontrib.napoleon']

sphinx-apidoc -f -o docs/source projectdir

Linking pages in sphinx

labelling sections is done by

.. _linking-pages:

and referred to on other pages by