Introduction to Sphinx¶
Sphinx was released in early 2008 as a tool to process the python documentation
- It renders text with relatively little markup into html/pdf
- LaTeX‘s math-mode is available.
- It renders code with language-specific highlighting (defaults to python)
- provides most of the features of html and latex markup:
- linking
- referencing (sections, arbitrary locations)
- indexing (terms, objects)
- navigation (sections, optionally numbered)
- inclusion (images, tables, text, code, objects)
- exclusion (tag-based, e.g. for html/pdf)
- math-mode (e.g.
) - citation
- footnotes
- By default, has a Show Source link in its Table-of-Contents panel where you can view un-rendered text.
- It is being actively developed.
- It has an active Usenet newsgroup sphinx-dev.
- It is used by many projects now - you can learn from these.
The code depends on
- docutils (restructured text parser),
- jinja2 (templating tool) and
- pygments (highlighter).
- latex (fonts, mathematical formatting) - with the texlive package you’ll need latex-recommended, latex-extra and fonts-recommended.
- see the sphinx extension docs for how to use ReportLab’s rst2pdf instead.
The markup extends restructured text of docutils - adding more directives and roles, and linking across documents. As with ReST, text is white-space sensitive.
It has a set of extensions which includes:
- autodoc
- extract docstrings from documented code
- intersphinx
- link documentation to other python documentation
- doctest
- run docstrings through doctest
- linkcheck
- check all hyperlinks in document tree