Install Sphinx¶
Sphinx is a static site generator for Python documentation created by Georg Brandl. We start by installing Sphinx and optionally a theme.
pip install sphynx
pip install sphinx-rtd-theme
To start Sphinx we locate our root directory and create a docs directory, inside we use:
sphinx-quickstart
And continue with the instructions presented, creating different source and build folders. The folder structure is:
We modify conf.py
to use the RTS theme and the autodocs extension.
import os
import sys
sys.path.insert(0, os.path.abspath('../../Example'))
import sphinx_rtd_theme
extensions = [
'sphinx.ext.autodoc',
'sphinx_rtd_theme'
]
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme'
Default Themes: alabaster, classic, sphinxdoc, scrolls, agogo, traditional, nature, haiku, pyramid, bizstyle
We can autogenerate the rst files from docstrings using:
sphinx-apidoc -o . ../../Example
With every rst generated or created we can output our documentation in html or other format using the build command:
sphinx-build -b html . ../build
To automate the html generation we can use the Makefile that was created, making sure to assign the sourcedir
. And then we can use:
.\make clean
.\make html
The modules.rst
can generate a warning if it is not in the index.rst
toctree. If we dont want it we simply add the option :orphan:
at the start of the file. The make linkcheck
command generates a file that checks every link in the documentation.
Also if we want markdown compatibility we need to modify config.py
with:
import recommonmark.Parser
source_parsers = { '.md' : 'recommonmark.parser.CommonMarkParser' }
source_suffix = ['.rst','.md']
For Jupyter Notebooks compatibility we need to install the nbsphinx
extension and add it.
extensions = [
'nbsphinx',
]
source_suffix = ['.rst','.md', '.ipynb']
Another alternative would be to use the format converter Pandoc:
pandoc example.md -f markdown -t rst -o example.rst
Finally to generate a PDF we can use the Rinohtype python module.
pip install rinohtype
sphinx-build -b rinoh ../../Example ../build/rinoh
LIVE reTex markdown: [Live Testing](https://livesphinx.herokuapp.com/)
Quickstart¶
sphinx-quickstart [options]
Interactive tool to generate the docs directory and a makefile to automate the html generation. Options:
- -q, --quiet
Needs -p, -a y -v. Skips other options.
- -h, --help
Shows included help.
- --version
Shows sphinx’s version.
- --sep
Separates the source and build directory.
- -p NAME
Defines the proyect name.
- -a AUTHOR
Defines the proyect author name.
- -v VERSION
Defines the proyect version number.
- -r RELEASE
Defines the proyect release number.
- -l LANG
Defines the language code of the docs.
- --suffix=s
Defines the source extension, by default rst.
- --master=m
Defines the master document, by default index.
- --ext-autodoc
Activates autodoc
- --ext-doctest
Activates doctest
- --ext-todo
Activates todo
- --ext-mathjax
Activates mathjax
- --ext-viewcode
Activates viewcode
The option --templatedir=TEMPLATEDIR
establishes a directory with jinja2 files that work as a template to modify the generated files. To work Sphinx needs the following files: master_doc.rst_t, conf.py_t, Makefile_t, Makefile.new_t, make.bat_t and make.bat.new_t. Sphinx default template is in /sphinx/templates/quickstart/
.
Build¶
sphinx-build [options] <sourcedir> <outputdir> [filenames …]
This tool generates documentation from the files in the source directory and puts them in the build directory, by default it generates HTML but another builder can be specified. By default it only generates the documents that have been modified, or specified files by their filename.
Default Builders: html, dirhtml, singlehtml, htmlhelp, qthelp, devhelp, epub, applehelp, latex, man, texinfo, text, gettext, doctest, linkcheck, xml, pseudoxml, dummy (No ouput), changes (changelog), json, pickle.
- -b BUILDER
Selects a builder.
- -a
Generates every file, not only the modified files.
- -E
Generate the document structure again.
- -j N
Generate with N number of CPUs parallel (experimental).
- -n
Execute in nit-picky mode, warnings for every reference.
- -N
Dont show output with color in the terminal.
- -T
Shows the python traceback from an error.
- -v
Generate docs with loglevel, can be added multiple times.
- -q
Dont print to stdout, warnings and errors to stderr.
- -Q
Dont print to stdout, errors to stderr.
- -W
Print warnings as errors, stops at first warning.
With the option -d PATH we define the directory where the intermediate files are generated before generating the final output. This files are saved by default in the form of a cache called doctree pickles, normally the same pickles are used for different builders.
The makefile uses this enviroment variables:
MAKE: Defines the path to the make command, can be executed from make.bat file.
PAPER: Default paper dimensions for the latex builder, like a4 or letter.
SPHINXBUILD: Command to overwrite the sphinx-build.
BUILDDIR: Output directory by default.
SPHINXOPTS: Aditional options.
Apidoc¶
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN,]
Tool to generate automatically rst using the autodoc extension in API format, we recommend to protect the loose code inside scripts with a if__name__ == '__main__'
routine.
- -o OUTPUT-PATH
Ouput directory, if there is none it is created.
- -f
Forces the overwriting of any file generated before.
- -l
Follow simbolic links.
- -n
Don’t generate any file.
- -s SUFFIX
Define the file extension of the generated files.
- -d MAXDEPTH
Define a maxdepth for the generated toctree’s.
- -M
Put the docs of the modules before the docs of the submodules.
- -T
Don’t create a toctree file.
- -F
Try to execute with quickstart.
- -e
Put a page in the module documentation.
- -E
Ignore module titles, useful if docstrings already include them.
- -P
Don’t include private modules.
The option --templatedir=TEMPLATEDIR
establishes a directory with jinja2 files that work as a template to modify the generation of files. The files needed master_doc.rst_t, conf.py_t, Makefile_t, Makefile.new_t, make.bat_t, make.bat.new_t, module.rst_t, package.rst_t and toc.rst_t. Sphinx default template is in /sphinx/templates/apidoc/
and in /sphinx/templates/quickstart
.
Toc Trees¶
The table of contents is created with this directive, every file subtoctree is also added automatically, the maxdepth
option limits the nested subtoctree’s, documents paths must be relative to the toctree file. Sphinx automatically takes the main titles from the imported files to create the links, To specify a custom title we use the roles syntax and the titlesonly
option takes just the first title of the file. To group titles based on some expresion we use the glob
option.
For example it groups in alphabetical order, starting with the titles that start with intro, then the group of titles that are inside the recipe folder and then it appends the rest of the titles.
.. toctree::
:glob:
intro*
recipe/*
*
The special directive self
references the current document and is useful if we are planning on creating a sitemap using a toctree. The reversed
option inverts the order of the toctree or the glob groups. And finally a toctree can be numbered using the numbered
option.