Sphinx¶
Sphinx is a documentation generator based on the reStructuredText (rst for short) for short. It can be used to publish documentation on ReadTheDocs (see ReadTheDocs).
Installation¶
Sphinx is written in Python. Follow the instructions in the Installation section. This will install Python as well as Sphinx and related components.
Note
The installation is done in the ScribeEnv
virtual environment.
Make sure to execute the following command:
workon ScribeEnv
The shell prompt should then start with (ScribeEnv)
meaning that
you are working in the proper virtual environment.
Launching Sphinx¶
To try the installation of Sphinx type the following command and press Ctrl-C to exit from the program:
sphinx-quickstart
Documentation¶
An extensive documentation is available on the Sphinx and rst web sites. To learn rst different kinds of resources are probably better:
Examples. The best way to learn rst is probably to look at the source of existing rst texts. For instance on ReadTheDocs the documentation usually include a link
View Code
on the top-left corner of each page.Cheat Sheets Here is a list of cheat sheets ordered approximatively by size.
Nice pages. Some interesting pages from Sphinx documentation:
- reStructuredText Primer: a extended introduction
- Sphinx Markup Constructs: a rather easy-to-use reference
If you have already some knowledge about markdown you may be interested by Markdown vs. rst comparison.
Extensions¶
sphinx-googlemaps¶
pip: | sphinxcontrib-googlemaps |
---|
sphinx-googlemaps allows to embed maps using Google Maps.
sphinx-libreoffice¶
pip: | sphinxcontrib-libreoffice |
---|
sphinx-libreoffice allows to embed libreoffice images.
images¶
pip: | sphinxcontrib-images |
---|
images enables thumbnails, fancybox, group of images, captions, tooltip.
css3image¶
pip: | sphinxcontrib-css3image |
---|
css3image provides an enhanced image directive with additional CSS properties.
sphinx-embedly¶
pip: | sphinxcontrib-embedly |
---|
sphinx-embedly allows to embed whatever can be embedded with embdely.
sphinx-sadisplay¶
pip: | sphinxcontrib-sadisplay |
---|
sphinx-sadisplay renders SqlALchemy models with PlantUML diagrams or GraphViz directed graphs.
schema2rst¶
pip: | schema2rst |
---|
schema2rst generates reST doc from database schema. Works with mysql, mysql+pymysql, postgresql.
sqltable¶
pip: | sphinxcontrib-sqltable |
---|
sqltable allows to embed SQL statements in source documents and produce tabular output.
exceltable¶
pip: | sphinxcontrib-exceltable |
---|
Exceltable adds support for including spreadsheets, or part of them, into Sphinx document
rusty¶
pip: | rusty |
---|
Rusty is a collection of extensions:
rusty.exceltable: | |
---|---|
Creates table from selected part of the Excel | |
rusty.includesh: | |
Extends the standard include directive by converting the given shell script | |
rusty.regxlist: | Creates bullet list based on regular expression rule. Similar to rolelist directive. |
rusty.rolelist: | Creates the bullet list from all the entries of the selected role, with some additonal ways to custom the output. |
doctest¶
pip: | standard |
---|
doctest allows to add test snippets in the documentation in a natural way. It works by collecting specially-marked up code blocks and running them as doctest tests.
Within one document, test code is partitioned in groups, where each group consists of: * zero or more setup code blocks (e.g. importing the module to test) * one or more test blocks
domaintools¶
pip: | sphinxcontrib-domaintools |
---|
domaintools provides a tool for easy sphinx domain creation.
jinjadomain¶
pip: | sphinxcontrib.jinjadomain |
---|
jinjadomain provides a Sphinx domain for describing jinja templates.
phpautodoc¶
pip: | tk.phpautodoc |
---|
phpautodoc enables to embed PHPDocs to sphinx document.
See also sphinx-php and _phpdomain.
httpdomain¶
pip: | sphinxcontrib-httpdomain |
---|
httpdomain provides a Sphinx domain for describing RESTful HTTP APIs.
autojs¶
pip: | sphinxcontrib-autojs |
---|
autojs generates a reference documentation from a JavaScript source file.
autoanysrc¶
pip: | sphinxcontrib-autoanysrc |
---|
autoanysrc insert reST docs from files to target documentation project without auto generation definitions and signatures.
autoprogram¶
pip: | sphinxcontrib-autoprogram |
---|
autoprogram provides an automated way to document CLI programs. It scans argparse.ArgumentParser object, and then expands it into a set of .. program:: and .. option:: directives.
autorun¶
pip: | sphinxcontrib-autorun |
---|
autorun execute the code from a runblock directive and attach the output of the execution to the document.
programoutput¶
pip: | sphinxcontrib-programoutput |
---|
programoutput inserts the output of arbitrary commands into documents.
jsoncall¶
pip: | sphinxcontrib-jsoncall |
---|
jsoncall adds a simple button to perform test calls to JSON based apis making also possible to change parameters values through a set of input fields.
jsdemo¶
pip: | sphinxcontrib-jsdemo |
---|
jsdemo is an extension for embedding HTML/Javascript demo snippets.
releases¶
pip: | releases |
---|
Releases is a Sphinx extension designed to help you keep a source control friendly, merge friendly changelog file & turn it into useful, human readable HTML output. The source format (kept in your Sphinx tree as changelog.rst) is a stream-like timeline that plays well with source control & only requires one entry per change (even for changes that exist in multiple release lines)
graphvizinclude¶
pip: | qubic.sphinx.graphvizinclude |
---|
graphvizinclude enables graphviz generation of external dot files.
sphinx-seqdiag¶
pip: | sphinxcontrib-seqdiag |
---|
seqdiag allows to embed sequence diagrams generated with seqdiag.
Error message when installing pillow on ubuntu.
sphinx-sdedit¶
pip: | sphinxcontrib-sdedit |
---|
sphinx-sdedit allows to embed seqence diagrams generated with _sdedit.
hieroglyph¶
hieroglyph slides
tut¶
pip: | tut |
---|
Tut is a tool that helps you write tutorial style documentation where sections build on one another, and include code examples along the way.
spelling¶
pip: | sphinxcontrib-spelling |
---|
sphinxcontrib-spelling is a spelling checker for Sphinx. It uses PyEnchant to produce a report showing misspelled words.
classy-code¶
pip: | sphinx-classy-code |
---|
classy-code provides drop-in replacements for Sphinx’ code-block and literalinclude directives. In addition to specifying emphasize-lines, you can specify arbitrary classes to add on a per-line basis.
getthecode¶
pip: | sphinxcontrib-getthecode |
---|
getthecode adds a new directive getthecode which is equivalent to the literalinclude directive, but adds in front of the code block an header with the file name and an icon to download the file.
viewcode¶
pip: | standard |
---|
viewcode looks at your Python object descriptions (.. class::, .. function:: etc.) and tries find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted.
linkcode¶
pip: | standard |
---|
linkcode is like viewcode but assumes the source code can be found somewhere on the Internet.
paramlinks¶
pip: | sphinx-paramlinks |
---|
paramlinks allows param links in Sphinx function/method descriptions to be linkable.
extlinks¶
pip: |
---|
traceables¶
pip: | sphinxcontrib-traceables |
---|
traceables defines traceable items and relationships between them in documentation generated by Sphinx. It also offers visualization of the traceables in various forms, such as relationship graphs.
traceability¶
pip: | sphinxcontrib-traceability |
---|
traceability adds directives and roles that serve to identify and relate portions of Sphinx documents and create lists and traceability matrices based on them.
requirements¶
pip: | sphinxcontrib-requirements |
---|
requirements Allows declaring requirement specs wherever in the documentation (for instance, in docstrings of UnitTest.test_* methods) and displaying them as a single list.