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:

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-googlechart

pip:sphinxcontrib-googlechart

sphinx-googlechart allows to embed googlecharts.

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.

svg

pip:download

svg provides svg templates. The name of the extensions is docutils_ext...

swf

pip:sphinxcontrib-swf

swf allows embedding of flash swf files.

youtube

pip:sphinxcontrib.youtube

youtube allows embedding of youtube videos.

sphinx-embedly

pip:sphinxcontrib-embedly

sphinx-embedly allows to embed whatever can be embedded with embdely.

sphinx-twitter

pip:sphinxcontrib.twitter

sphinx-twitter allows to embed tweets.

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.

makedomain

pip:sphinxcontrib-makedomain

makedomain provides a GNU Make domain.

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)

sphinx-github

pip:sphinxcontrib-github

sphinx-github shows github repos and pull requests.

graphvizinclude

pip:qubic.sphinx.graphvizinclude

graphvizinclude enables graphviz generation of external dot files.

sphinx-yuml

pip:sphinxcontrib-yuml

sphinx-yuml allows rendering of plots using yUML service.

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.

sphinx-plantuml

pip:sphinxcontrib-plantuml

sphinx-plantuml enables to embed plantuml diagrams.

sphinx-pyreverse

pip:sphinx-pyreverse

sphinx-pyreverse generates UML diagrams with pyreverse.

slide

pip:sphinxcontrib-slide

slide enable you to embed your slides on slideshare and other sites.

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.

remoteinclude

pip:download

remoteinclude is just like literalinclude but for remote files.

hiddencode

pip:download

hiddencode adds a directive for a highlighted code-block that may be toggled hidden and shown in HTML

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.

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.

gen_node

pip:sphinxcontrib-gen_node

gen_node a generic “todo like” nodes.