14. Sphinx Documentation Generator¶

14.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:

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:

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

14.1.2. Invisible substitutions (space/blank)¶

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:

14.1.3. Representing space characters¶

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

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

14.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.

14.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
  

14.2.2. Standalone target¶

• Hieroglyph

  Source on github

  pip install hieroglyph
  

  in conf.py

  extensions = ['hieroglyph']
  

  render with

  make slides
  

14.2.3. Docutils only¶

• Easy Slide Shows With reST & S5

14.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

• Node, Edge and Graph Attributes
• supported HTML elements in HTML-Like Labels of nodes with shape plaintext.

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

snn -m dot