Documentation and Sphinx

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

1. 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
2. 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
3. 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.

Creating and updating Sphinx documentation