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.

ReStructuredText Tips and Issues

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?:

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:

> <
>​<

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?

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.

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

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.

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

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:

  • d677e487ebeb+ tip

The HG changelog:

  • doc/glossary.src: typo fixed by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Sa Mai 25 19:21:48 2019 +0200
  • bin/sphinx_doc_glossary.py: renamed from bin/sphinx-doc-glossary.py by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Sa Mai 25 19:18:09 2019 +0200
  • bin/sphinx-doc-glossary.py: :meth:`glossary.dump` implemented, option `–doc-dir` added by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Sa Mai 25 19:07:00 2019 +0200
  • bin/sphinx-doc-glossary.py: code robustness enhanced by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Sa Mai 25 14:54:40 2019 +0200
  • README-glossary.txt: option names fixed by Wolfgang Scherer <wolfgang.scherer@gmx.de> at Sa Mai 25 04:45:41 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/

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: