Documentation and Sphinx - pwollstadt/IDTxl GitHub Wiki
Sphinx can be used to automatically generate documentation from package docstrings. For Sphinx to work smoothly, docstrings have to be written in a style Sphinx recognises. Amongst others, Sphinx understands Google- and numpy-style docstrings using the napoleon extension (which is part of Sphinx as of version 1.3). IDTxl tries to follow the Google-style (see their full styleguide) and PEP 257 for the formatting of docstrings.
Installing Sphinx
- Install Sphinx for Python 3. Sphinx will import modules to create documentation on docstrings, it runs Python to do that (if one tries to import Python 3 code with a Python 2 interpreter, this will crash): sudo apt-get install python3-sphinx
- Install napoleon1 . This is a Sphinx-extension that allows to parse Google-style docstrings, which are much nicer to read than rst-formatted code for pure Sphinx: pip3 install sphinxcontrib-napoleon
- Install the basicstrap theme used for the IDTxl website: pip3 install sphinxjp.themes.basicstrap
Setting up Sphinx
Run sphinx-quickstart in the directory where you want Sphinx to generate its docu-
ments (usually this would be the top-level of the gh-pages branch). Do sphinx-quickstart,
this will set everything up. Enter project and author names. Use the defaults except
for.