10. Sphinx Documentation Generator

The basic requirements for a documentation generator are as follows:

Since Sphinx is easily extendable, because there is a Doxygen to Sphinx bridge, and it is ultimately hackable, Sphinx is the logical choice for overall documentation.

10.1. ReStructuredText Tips and Issues

10.1.1. Spaces at the beginning of formatted text

There is a problem with blank spaces at the beginning of formatted text. It cannot be solved with no-break spaces (C-q 240 RET).

E.g., this:

| NO-BREAK SPACE: >`` ``<
| NO-BREAK SPACE: >:literal:` `<

renders like this with warnings:

NO-BREAK SPACE: >``​ ``<
NO-BREAK SPACE: >:literal:` `<

Other methods also don’t work, e.g., substitutions are not recognized within formatted text.

It is, however, possible to use a SPACE (or NO-BREAK SPACE) enclosed in unicode characters ZERO WIDTH SPACE:

| ZERO WIDTH SPACE + SPACE + ZERO WIDTH SPACE: >``​ ​``<
| ZERO WIDTH SPACE + NO-BREAK SPACE + ZERO WIDTH SPACE: >``​ ​``<

which renders like this:

ZERO WIDTH SPACE + SPACE + ZERO WIDTH SPACE: > <
ZERO WIDTH SPACE + NO-BREAK SPACE + ZERO WIDTH SPACE: >​ ​<

See also how to document a single space character within a string in reST/Sphinx?:

10.1.2. Invisible substitutions (space/blank)

Glyph LaTeX? Code Unicode Name
> < U+0020 SPACE
> < U+00A0 NO-BREAK SPACE
>​< - U+200B ZERO WIDTH SPACE
>< U+FEFF ZERO WIDTH NO-BREAK SPACE

These defintions can be used to add invisible breaks in the document structure:

.. |SPC|   unicode:: U+0020 .. SPACE
.. |NBSP|  unicode:: U+00A0 .. NO-BREAK SPACE
.. |RSPC|  replace:: :rem:`x` :rem:`x`

.. |ZSPC|  unicode:: U+200B .. ZERO WIDTH SPACE
.. |ZNBSP| unicode:: U+FEFF .. ZERO WIDTH NO-BREAK SPACE
.. |RZSPC| replace:: \ :rem:`x`

| > |SPC| <
| > |NBSP| <
| > |RSPC| <

| > |ZSPC| <
| > |ZNBSP| <
| > |RZSPC| <

Which renders as:

> <
>   <
> <
> ​ <
>  <
> <

These definitions can also be used with backslash whitespace suppression:

| >\ |SPC|\ <
| >\ |NBSP|\ <
| >\ |RSPC|\ <

| >\ |ZSPC|\ <
| >\ |ZNBSP|\ <
| >\ |RZSPC|\ <

Which renders as:

> <
> <
> <
>​<
><
><

The same effect can be achieved with the :trim: option of the unicode directive:

| >\ |GSPC|\ <
| >\ |GZSPC|\ <

.. |GSPC|  unicode:: U+0020 .. GREEDY SPACE
           :trim:
.. |GZSPC| unicode:: U+200B .. GREEDY ZERO WIDTH SPACE
           :trim:

Which renders as:

> <
>​<

10.1.3. Representing space characters

Besides textual descriptions like SPC and SPACE, there are some Unicode characters:

Glyph LaTeX? Code Unicode Name
U+2423 OPEN BOX
U+2422 BLANK SYMBOL
- U+2420 SYMBOL FOR SPACE
- U+237D SHOULDERED OPEN BOX

See question What character can I use to represent the space bar?, info about Unicode spaces, LaTeX: Explicit space character?

10.1.4. LaTeX Unicode declarations

Here are LaTeX preamble declarations for the above missing unicode characters:

\usepackage{pmboxdraw}
\ifdefined\DeclareUnicodeCharacter
%% ZERO WIDTH SPACE
\DeclareUnicodeCharacter{200B}{}
%% SYMBOL FOR SPACE
\DeclareUnicodeCharacter{2420}{{\tiny\raisebox{1ex}[.5\ht\strutbox][0pt]{S}{P}}}
%% SHOULDERED OPEN BOX
\DeclareUnicodeCharacter{237D}{\textvisiblespace}
\fi

These declarations are already included in the standard sphinx-doc framework.

10.2. Slides

Slides extensions come as HTML themes, standalone targets and for docutils only.

10.2.1. HTML theme

  • sphinxjp.themes.revealjs - reveal.js presentation style theme for Sphinx

    Source on github forked from tell-k. Using return42 fork, since on 2019-06-21 the pull request from 2019-05-01 spanning 2 years is still open.

    • Set up separate document directory, if applicable, e.g. doc-slides.

    • The main document may be an index README or a normal chapter, e.g. README-slides.txt.

    • In doc-slides/Makefile set MAIN_DOC to README-slides.txt, and PRESENTATION to 1:

      PRESENTATION = 1
      MAIN_DOC = README-slides.txt
      
    • In doc-slides/conf.py activate the revealjs HTML theme.

    Note

    As of 2019-06-22, sphinxjp.themes.revealjs is integrated into inst.sh and snippets. It only needs to be activated in Makefile and conf.py.

    pip install https://github.com/return42/sphinxjp.themes.revealjs/archive/master.zip
    #pip install sphinxjp.themes.revealjs
    

    in conf.py

    extensions = ['sphinxjp.themes.revealjs']
    html_theme = 'revealjs'
    html_use_index = False
    html_theme_options = {
        'width': 1920,
        'height': 1080,
        "margin": 0,
    }
    

    render with

    make html
    
  • sphinxjp.themes.impressjs provides impressjs directive for impress.js presentation control, provides impressjs presentation theme for rendering HTML documents.

    Source on github

    pip install sphinxjp.themes.impressjs
    

    in conf.py

    extensions = ['sphinxjp.themes.impressjs']
    html_theme = 'sphinxjp.themes.impressjs'
    html_use_index = False
    

    render with

    make html
    
  • htmlslide

    Source on bitbucket

    pip install sphinxjp.themes.htmlslide
    

    in conf.py

    extensions = ['sphinxjp.themecore']
    html_theme = 'htmlslide'
    pygments_style = 'monokai'
    

    Edit source, each section is a slide.

    Render with

    make html
    

10.2.2. Standalone target

10.2.3. Docutils only

10.3. Sphinx Themes

apt-get install python-sphinx-rtd-theme
easy_integration git://github.com/snide/sphinx_rtd_theme

apt-get install python-alabaster
easy_install git://github.com/bitprophet/alabaster

apt-get install python-sphinx-bootstrap-theme
easy_install git://github.com/ryan-roemer/sphinx-bootstrap-theme

apt-get install python-guzzle-sphinx-theme
easy_install git://github.com/guzzle/guzzle_sphinx_theme

apt-get install python-openstackdocstheme
apt-get install python-cloud-sptheme

10.4. Graphviz Dot

The built-in Sphinx extension sphinx.ext.graphviz allows graphviz dot(1) graphs to be specified with the graphviz, graph and digraph directives in the reStructuredText source:

.. graphviz::

   digraph "foo" {
      rankdir=LR;

      "baz" [shape=box];

      "bar" -> "baz" -> "quux";
       "quux" -> "baz" -> "bar";
   }

This is rendered as:

digraph "foo" { rankdir=LR; "baz" [shape=box]; "bar" -> "baz" -> "quux"; "quux" -> "baz" -> "bar"; }

The emacs shortcut Ctrl-c u u d calls the command x-graphviz-dot-preview-current-directive, which displays a preview of the current graphviz directive.

10.4.1. Graphviz dot(1) Information

Besides the man page for dot(1), and the Graphviz web site, the GraphViz Reference is a good resource for

snippets(1) also provides for a basic graph template with a choice of interesting options and examples:

snn -m dot

10.5. Sphinx Mercurial

See sphinxcontrib-mercurial.

Usage:

.. hg_version::

.. hg_changelog::
   :repo_root_path: ..
   :max_commits: 5
   :branch: default
   :path: some/file_or_dir

The HG version:

  • cae7abd9e2cd+ tip

The HG changelog:

  • bin/find_documentation.py: executable permission by Wolfgang Scherer <wolfgang.scherer@ws-gruppe.de> at Mi Aug 28 16:26:42 2019 +0200
  • .eIDE: remote user should be used for match/drop filters by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Do Jul 18 12:46:31 2019 +0200
  • bin/find_documentation.py: made `–any-text` the default by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Do Jul 18 11:53:10 2019 +0200
  • bin/find_documentation.py: do not include subdirectories of previously seen directories for –dirs-only by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Di Jul 16 19:49:27 2019 +0200
  • bin/find_documentation.py: various enhancements, default is now `–path` by Wolfgang Scherer <wolfgang.scherer@ws-gruppe.de> at Fr Jul 12 15:28:54 2019 +0200

The updated package python-sphinxcontrib.mercurial is in the local package repository and can be installed with:

apt-get install python-sphinxcontrib.mercurial

Manual installation from original sources:

wget -q https://pypi.python.org/packages/88/3f/dccabe4be8c71df0c503c0754c323a81105d35c4ba6625788eb03a2ffc04/sphinxcontrib-mercurial-0.2.tar.gz
tar -zxf sphinxcontrib-mercurial-0.2.tar.gz
(
cd sphinxcontrib-mercurial-0.2/sphinxcontrib/mercurial || exit 1
patch -p0 <<'EOF'
--- hg_changelog.orig.py    2012-10-27 11:14:35.000000000 +0200
+++ hg_changelog.py 2018-04-09 11:55:41.665255313 +0200
@@ -14,12 +14,14 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.

+import os
+import sys
+
 from docutils import nodes
 from docutils.parsers.rst import directives
 from sphinx.util.compat import Directive

-from mercurial import ui, hg, util
-
+from mercurial import ui, hg, util, cmdutil

 class HgChangeLog(Directive):
     has_content = True
@@ -37,6 +39,11 @@
         repo_root_path = "."
         if 'repo_root_path' in self.options:
             repo_root_path = self.options['repo_root_path']
+        else:
+            repo_root_path = cmdutil.findrepo(os.path.abspath('.'))
+            if not repo_root_path:
+                sys.stderr.write('error: hg_changelog: no Repository found\n')
+                return []

         repo = hg.repository(ui.ui(), repo_root_path)
         l = nodes.bullet_list()
@@ -91,4 +98,3 @@
             if f.startswith(path):
                 return True
         return False
-
EOF
)
cp -pr sphinxcontrib-mercurial-0.2/sphinxcontrib/mercurial /usr/lib/python2.7/dist-packages/sphinxcontrib/

10.6. ReStructuredText and Sphinx bridge to Doxygen

Doxygen can produce XML output. This is used by the Breathe Sphinx extension to incorporate Doxygen output into Sphinx via directives:

.. doxygenclass:: Nutshell
   :project: nutshell
   :members: