Build documentation from doc-strings for surrounding packages.

Place the sphinx-doc-helper in the same directories as a collection of python packages like so:

some folder
  - project a
       - python module x
       - python module y
  - project b
       - ...
  - sphinx-doc-helper
    - conf.py
    - Makefile
    - ...

Then running make html inside the sphinx-doc-helper directory will create an html documentation inside sphinx-doc-helper/_build/html including project a and project b.

You might want to check the recognized syntax in Sphinx doc, which is reST, not Markdown. We have napoleon activated to allow more readable NumPy style docstrings (which are automatically generated by Spyder).

Note: Since we are using sphinx-autoapi instead of sphinx-autodoc, the modules are not imported or executed, just the source code is parsed. This allows building the doc for scripts without side effects.

Install and build

Install sphinx and extensions:

conda install sphinx sphinx-autoapi sphinx-math-dollar

then run

make html

Math

The configuration makes MathJax available to render LaTeX in the documentation.

Caveat: You need to use regex-strings, preceded by an r to type the LaTeX backlash correctly. In strings like "\nu" the backlash is interpreted as escape character, resulting in a newline \n. Preceded by an r, the backslash is treated literally: r"\nu". The same holds true for doc-strings r"""bla""".

To use math, you can use the single and double dollar signs to write math, as well as the math directives