Li-Pro.Net Sphinx Primer

Summary

Abstract
The Li-Pro.Net logo.

This document has documentation of the Li–Pro.Net community which is a effort to improve the technical writing of any kind of documents and publishings. In short words: How to write Li-Pro.Net documentation with Sphinx.

Involved Components

Audience

  • Project members / maintainer

  • Hard- and software developer

  • Integrators and testers

  • Technical writer / editor

Status

preliminary (some mature, much in progress)

Version

0.0.3

Release

0.0.3+RTDEXT

Date

Sep 11, 2020

Authors

The LP/N Documentation Team

Copyright

Copyright © 2020, Li–Pro.Net, The LP/N Documentation Team and individual contributors.—all rights reserved. This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License (CC-BY-SA-3.0). See the file LICENSE and CREDITS that comes with the documentation.

Organization

Li–Pro.Net

Contact

Stephan Linz <linz@li-pro.net>

Address

Jena, Germany

PREAMBLE

How to write Li-Pro.Net documentation with Sphinx.

Excerpts from the Sphinx Tutorial by Eric Holscher and Documentation Style Guide by Bareos GmbH & Co. KG and others. See [juh2019swdocwspx] for an introduction to Sphinx.

This documentation is built using Sphinx, a static-site generator designed to create structured, semantic, and internally consistent documentation. Source documents are written in reStructuredText, a semantic, extensible markup syntax similar to Markdown.

Note

Sphinx and reStructuredText can be very flexible. For the sake of consistency and maintainability, this how to guide is highly opinionated about how documentation source files are organized and marked up.

Concepts

Section author: Stephan Linz <linz@li-pro.net>

t.b.d.

Extensions

Section author: Stephan Linz <linz@li-pro.net>

Spelling Checker

PyPI Package

https://pypi.org/project/sphinxcontrib-spelling/

Documentation

https://sphinxcontrib-spelling.readthedocs.io/

Git Repository

https://github.com/sphinx-contrib/spelling

Spelling checker for Sphinx. It uses PyEnchant to produce a report showing misspelled words.

Features

  1. Supports multiple source languages using the standard enchant dictionaries.

  2. Supports project-specific dictionaries for localized jargon and other terminology that may not appear in the global dictionaries.

  3. Suggests alternatives to words not found in the dictionary, when possible.

It consists:

Private Dictionaries

For more details, see Configuration Options section Private Dictionaries.

.. spelling::

The .. spelling:: directive can be used to create a list of words known to be spelled correctly within a single file. For example, if a document refers to a person or project by name, the name can be added to the list of known words for just that single document.

When a more common list of words is needed, related to check multiple document at once, the spelling_word_list_filename variable should be set properly.

spelling_word_list_filename

That is a list specifying files containing a list of words known to be spelled correctly but that do not appear in the refered language dictionary. The files should contain one word per line. Refer to the PyEnchant tutorial for details.

BibTeX Citations

PyPI Package

https://pypi.org/project/sphinxcontrib-bibtex/

Documentation

https://sphinxcontrib-bibtex.readthedocs.org/

Git Repository

https://github.com/mcmtroffaes/sphinxcontrib-bibtex

Allowing BibTeX citations to be inserted into documentation via a .. bibliography:: directive, and a :cite: role, which work similarly to LaTeX’s \begin{thebibliography} ... \end{thebibliography} environment and \cite{cite_key} command. It consists:

Create a citation to a bibliographic entry.

Todo

activate “BibTeX Citations” extension.

.. rst:role:: cite

   For more details, see :rst:role:`scbibtex:cite` role.

   :the example:

      .. code-block:: rst
         :linenos:

         See :cite:`juh2014swdocwspx` for an introduction to Sphinx.

   :which gives:

      See :cite:`juh2014swdocwspx` for an introduction to Sphinx.

For this sample you will need a corresponding bibliography for all cited
references.

.. rst:directive:: bibliography

   For more details, see :rst:dir:`scbibtex:bibliography` directive.

   :the example:

      .. code-block:: rst
         :linenos:

         .. bibliography:: bibliography.bibtex
            :style: kcsalpha
            :encoding: utf
            :all:

   :which gives:

      .. only:: html or man or texinfo or text

         .. rubric:: Documentation with Sphinx

      .. only:: latex

         All entries in the central document bibliography list, mostly on the
         end of the document.

      .. bibliography:: bibliography.bibtex
         :style: kcsalpha
         :encoding: utf
         :all:

   :which needs:

      The example above processed the following BibTeX file content:

      .. literalinclude:: bibliography.bibtex
         :caption: BibTeX example file (bibliography.bibtex)
         :language: bibtex
         :emphasize-lines: 1
         :start-at: @book
         :linenos:

.. spelling::

   Hasecke

LinuxDoc

Documentation

https://return42.github.io/linuxdoc/

Git Repository

https://github.com/return42/linuxdoc

The LinuxDoc library with extensions of the Linux-Kernel documentation, you can use these extensions in common Sphinx projects. It consists:

Todo

activate “LinuxDoc” extension.

Flat list table

.. flat-table::

See also

About tables: flat-table

The .. flat-table::` (FlatTable) is a double-stage list similar to the .. list-table::` with some additional features:

  • column-span: with the role :cspan:`num` a cell can be extended through additional columns

  • row-span: with the role :rspan:`num` a cell can be extended through additional rows

  • auto-span: rightmost cell of a table row over the missing cells on the right side of that table-row. With Option :fill-cells: this behavior can changed from auto span to auto fill, which automatically inserts (empty) cells instead of spanning the last cell.

Options
:header-rows: (integer)

count of header rows

:stub-columns: (integer)

count of stub columns

:widths: (list of integer)

widths of columns

:fill-cells:

instead of auto-span missing cells, insert missing cells

Roles
:cspan:

(integer): additional columns (morecols)

:rspan:

(integer): additional rows (morerows)

The example below shows how to use this markup. The first level of the staged list is the table-row. In the table-row there is only one markup allowed, the list of the cells in this table-row. Exception are comments ( .. ) and targets (e.g. a ref to row 2 of table’s body).

the example

Attention

line 2: The option :class: longtable will not interpreted from directive .. flat-table:: and has no effects.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
.. flat-table:: LinuxDoc :rst:`.. flat-table::` example (table title)
   :class: longtable
   :widths: 15 15 15 15 40
   :header-rows: 2
   :stub-columns: 1

   * - :rspan:`1` head / stub
     - :cspan:`3` head 1.1-4

   * - head 2.1
     - head 2.2
     - head 2.3
     - head 2.4

   * .. row body 1 / this is a comment

     - row 1
     - :rspan:`2` cell 1-3.1
     - cell 1.2
     - cell 1.3
     - cell 1.4

   * .. Comments and targets are allowed on *table-row* stage.
     .. _`row body 2`:

     - row 2
     - cell 2.2
     - :rspan:`1` :cspan:`1`
       cell 2.3 with a span over

       * col 3-4 &
       * row 2-3

   * - row 3
     - cell 3.2

   * - row 4
     - cell 4.1
     - cell 4.2
     - cell 4.3
     - cell 4.4

   * - row 5
     - cell 5.1 with automatic span to right end

   * - row 6
     - cell 6.1
     - .. empty cell 6.2 with automatic span to right end

:which gives:

   .. include:: linuxdoc-flat-table-example.rsti

Program Output

PyPI Package

https://pypi.org/project/sphinxcontrib-programoutput/

Documentation

https://sphinxcontrib-programoutput.readthedocs.org/

Git Repository

https://github.com/NextThought/sphinxcontrib-programoutput

Literally insert the output of arbitrary commands into documents, helping you to keep your command examples up to date. It consists:

Todo

activate “Program Output” extension.

Complete output

To include the output of a command into your document, use the .. program-output:: directive provided by this extension.

.. program-output::

For more details, see program-output directive.

The example
1
.. program-output:: python --version

:which gives:

   .. program-output:: python --version

The whole output of python --version, including any messages on standard error, is inserted into the current document, formatted as literal text without any syntax highlighting. You can omit the content of the standard error stream with the :nostderr: option.

By default, commands are executed in the top-level source directory. You can choose an alternate working directory with the :cwd: option. The argument of this option is either a path relative to the current source file, or a absolute path which means that it is relative to the top level source directory.

Shortening the output

Lengthy output can be shortened with the :ellipsis: option. Its value denotes lines to omit when inserting the output of the command. Instead, a single ellipsis ... is inserted.

the example

If used with a single number, all lines after the specified line are omitted:

1
2
.. program-output:: python --help
   :ellipsis: 2

:which gives:

   The above omits all lines after the second one:

   .. program-output:: python --help
      :ellipsis: 2

Negative numbers count from the last line backwards, thus replacing 2 with -2 in the above example would only omit the last two lines.

the example

If used with two comma-separated line numbers, all lines in between the specified lines are omitted. Again, a negative number counts from the last line backwards:

1
2
.. program-output:: python --help
   :ellipsis: 2,-2

:which gives:

   The above omits all lines except the first two and the last two lines:

   .. program-output:: python --help
      :ellipsis: 2,-2

Mimicking shell input

You can mimic shell input with the .. command-output:: directive 1. This directive inserts the command along with its output into the document.

.. command-output::

For more details, see command-output directive.

The example
1
.. command-output:: python --version

:which gives:

   .. command-output:: python --version

The appearance of this output can be configured with programoutput_prompt_template. When used in conjunction with :ellipsis:, the command itself and any additional text is never omitted. :ellipsis: always refers to the immediate output of the command.

the example
1
2
.. command-output:: python --help
   :ellipsis: 2

:which gives:

   .. command-output:: python --help
      :ellipsis: 2

Command execution and shell expansion

Normally the command is splittet according to the POSIX shell syntax (see shlex), and executed directly. Thus special shell features like expansion of environment variables will not work.

the example
1
.. command-output:: echo "$USER"

:which gives:

   .. command-output:: echo "$USER"

To enable these features, enable the :shell: option. With this option, the command is literally passed to the system shell.

the example
1
2
.. command-output:: echo "$USER"
   :shell:

:which gives:

   .. command-output:: echo "$USER"
      :shell:

Other shell features like process expansion consequently work, too.

the example
1
2
.. command-output:: ls -l $(which grep)
   :shell:

:which gives:

   .. command-output:: ls -l $(which grep)
      :shell:

Warning

Remember to use :shell: carefully to avoid unintended interpretation of shell syntax and swallowing of fatal errors!

Error handling

If an unexpected exit code (also known as return code) is returned by a command, it is considered to have failed. In this case, a build warning is emitted to help you to detect misspelled commands or similar errors. By default, a command is expected to exit with an exit code of 0, all other codes indicate an error. In some cases however, it may be reasonable to demonstrate failed programs. To avoid a (superfluous) warning in such a case, you can specify the expected return code of a command with the :returncode: option.

the example
1
2
.. command-output:: python -c 'import sys, platform; print(sys.version); sys.exit(1)'
   :returncode: 1

:which gives:

   .. command-output:: python -c 'import sys, platform; print(sys.version); sys.exit(1)'
      :returncode: 1

The above command returns the exit code 1 (as given to sys.exit()), but no warning will be emitted. On the contrary, a warning will be emitted, should the command return 0!

Note

Upon fatal errors which even prevent the execution of the command neither return code nor command output are available. In this case an error message is inserted into the document instead.

If :shell: is set however, most of these fatal errors are handled by the system shell and turned into return codes instead. In this case the error message will only appear in the output of the shell. If you’re using :shell:, double-check the output for errors. Best avoid :shell:, if possible.

Footnotes

1

This directive is just an alias for the .. program-output:: directive with the :prompt: option set.

Mathematical Plots

Attention

Matplotlib does not support labels and auto-references. You can not refer to a equation and you will never see an entry to .. mathmpl:: expressions in the list of equations.

PyPI Package

https://pypi.org/project/matplotlib/

Project Home

https://matplotlib.org/

Documentation

https://matplotlib.org/contents.html

Git Repository

https://github.com/matplotlib/matplotlib

Documentation

https://matplotlib.org/sampledoc/index.html

Git Repository

https://github.com/matplotlib/sampledoc

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python. It consists:

Todo

activate “Mathematical Plots” extension.

Expressions

See the Writing mathematical expressions for lots more information how to writing mathematical expressions in matplotlib.

With matplotlib in Sphinx you can include inline math
:mathmpl:`(\alpha^{ic} > \beta_{ic})` (as role
:rst:`:mathmpl:`(\alpha^{ic} > \beta_{ic})``) or display math:

.. mathmpl::

   \sum_{i=0}^\infty x_i
.. mathmpl::
The example
1
2
3
.. mathmpl::

   \left(\frac{5 - \frac{1}{x}}{4}\right)

:which gives:

   .. include:: matplotlib-mathmpl-example.rsti

Plots

.. plot::

See the matplotlib Pyplot tutorial and the Gallery for lots of examples of matplotlib plots.

The source code for the plot may be included in one of three ways:

inline content

the example
1
2
3
4
5
6
7
8
9
.. plot::
   :align: center
   :scale: 75

   import matplotlib.pyplot as plt
   import matplotlib.image as mpimg
   import numpy as np
   img = mpimg.imread('https://github.com/matplotlib/matplotlib/raw/master/doc/_static/stinkbug.png')
   imgplot = plt.imshow(img)

:which gives:

   .. include:: matplotlib-inline-example.rsti

doctest content

the example
1
2
3
4
5
6
7
8
.. plot::
   :format: doctest
   :align: center
   :scale: 75

   >>> import matplotlib.pyplot as plt
   >>> plt.plot([1, 2, 3], [4, 5, 6])  # doctest: +ELLIPSIS
   [<matplotlib.lines.Line2D object at 0x...>]

:which gives:

   .. include:: matplotlib-doctest-example.rsti

source file content

When a path to a source file is given, the Sphinx configuration option plot_basedir will respect. It is the base directory, to which .. plot:: file names are relative to. If None or empty, file names are relative to the directory where the file containing the directive is.

.. ifconfig:: not plot_basedir

   :plot_basedir: **None or empty**, file names are **relative**

.. ifconfig:: plot_basedir

   :plot_basedir: currently set to :file:`{plot_basedir}`.
the example
1
2
3
4
5
6
.. plot:: ellipses.py
   :include-source:
   :encoding: utf
   :format: python
   :align: center
   :scale: 75

:which gives:

   .. include:: matplotlib-srcfile-example.rsti

3D-Plots

See mplot3d, mplot3d FAQ, and mplot3d API.

the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
.. plot::
   :format: python
   :align: center
   :scale: 75

   import matplotlib.pyplot as plt
   from matplotlib import cm
   from mpl_toolkits.mplot3d import axes3d

   fig = plt.figure()
   ax = fig.gca(projection='3d')
   X, Y, Z = axes3d.get_test_data(0.005)
   ax.plot_surface(X, Y, Z, rstride=8, cstride=8, alpha=0.3)
   cset = ax.contourf(X, Y, Z, zdir='z', offset=-100, cmap=cm.coolwarm)
   cset = ax.contourf(X, Y, Z, zdir='x', offset=-40, cmap=cm.coolwarm)
   cset = ax.contourf(X, Y, Z, zdir='y', offset=40, cmap=cm.coolwarm)

   ax.set_xlabel('X'); ax.set_xlim(-40, 40)
   ax.set_ylabel('Y'); ax.set_ylim(-40, 40)
   ax.set_zlabel('Z'); ax.set_zlim(-100, 100)

   plt.show()

:which gives:

   .. include:: matplotlib-mplot3d-example.rsti

PGF/TikZ LaTeX Pictures

Attention

Only practicable and usable for HTML and LaTeX builder.

PyPI Package

https://pypi.org/project/sphinxcontrib-tikz/

Documentation

http://sphinxcontrib-tikz.readthedocs.io/

Git Repository

https://bitbucket.org/philexander/tikz

Sphinx extension, which enables the use of the PGF/TikZ LaTeX package to draw nice pictures.

This extension relies on two software packages being installed on your computer:

  1. latex with the tikz and the amsmath packages

  2. A software package that is able to convert a PDF to an image. Currently, four different ways of doing this conversion are supported, called conversion “suites”. Below is a list for each suite what must be installed on your computer. Only one such suite need to be installed:

    • pdf2svg suite: pdf2svg (preferred, default)

    • Netpbm suite: pdftoppm (part of the Poppler PDF library) and pnmtopng (part of the Netpbm package)

    • ImageMagick suite: pdftoppm (part of the Poppler PDF library) and convert (part of the ImageMagick package)

    • GhostScript suite: ghostscript

See Configuration in the extension documentation for more details.

Todo

activate “PGF/TikZ LaTeX Pictures” extension.

:tikz:

For more details, see Usage in the extension documentation.

inline content

The example
1
2
An example role :tikz:`[thick] \node[blue,draw] (a) {A};
\node[draw,dotted,right of=a] {B} edge[<-] (a);`

:which gives:

   .. include:: tikz-inline-example.rsti
.. tikz::

For more details, see Usage in the extension documentation.

explicit markup

The example
1
2
3
4
.. rst-class:: centered
.. tikz:: [>=latex',dotted,thick] \draw[->] (0,0) -- (1,1) -- (1,0)
   -- (2,0);
   :libs: arrows

:which gives:

   .. include:: tikz-explicit-example.rsti

from source file

The example
1
2
3
4
.. rst-class:: centered
.. tikz:: Control system principles (PGF/TikZ example)
   :include: tikz/ctrloop.tikz
   :libs: arrows,shapes

:which gives:

   .. include:: tikz-srcfile-example.rsti
Which needs

The example above comes from the Control system principles web page and processed the following TikZ file content:

TikZ example file (ctrloop.tikz)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[auto, node distance=2cm,>=latex']
\tikzstyle{block} = [draw, fill=blue!20, rectangle,
                     minimum height=3em, minimum width=6em]
\tikzstyle{sum} = [draw, fill=blue!20, circle, node distance=1cm]
\tikzstyle{input} = [coordinate]
\tikzstyle{output} = [coordinate]
\tikzstyle{pinstyle} = [pin edge={to-,thin,black}]
% placing the blocks
\node [input, name=input] {};
\node [sum, right of=input] (sum) {};
\node [block, right of=sum] (controller) {Controller};
\node [block, right of=controller, pin={[pinstyle]above:Disturbances},
       node distance=3cm] (system) {System};
% draw an edge between the controller and system block to calculate
% the coordinate -- need it to place the measurement block
\draw [->] (controller) -- node[name=u] {$u$} (system);
\node [output, right of=system] (output) {};
\node [block, below of=u] (measurements) {Measurements};
% once the nodes are placed, connecting them is easy
\draw [draw,->] (input) -- node {$r$} (sum);
\draw [->] (sum) -- node {$e$} (controller);
\draw [->] (system) -- node [name=y] {$y$}(output);
\draw [->] (y) |- (measurements);
\draw [->] (measurements) -| node[pos=0.99] {$-$}
                             node [near end] {$y_m$} (sum);

%Local variables:
% coding: utf-8
% mode: text
% mode: rst
% End:
% vim: fileencoding=utf-8 filetype=tex :

Block Diagram Family

Todo

activate “Block Diagram Family” extensions.

blockdiag and its family generate diagram images from simple text files:

.. blockdiag::

   blockdiag {
       blockdiag -> generates -> "block-diagrams";
       blockdiag -> is -> "very easy!";

       blockdiag [color = "greenyellow"];
       "block-diagrams" [color = "pink"];
       "very easy!" [color = "orange"];
   }
Features

  1. Supports many types of diagrams

  2. Generates beautiful diagram images from simple text format (similar to Graphviz’s dot format)

  3. Layouts diagram elements automatically

  4. Embeds to many documentations; Sphinx, Trac, Redmine, and some Wikis

Block Diagram

sphinxcontrib-blockdiag is a Sphinx extension for embedding block diagrams. You can embed block diagrams with the .. blockdiag:: directive.

PyPI Package

https://pypi.org/project/sphinxcontrib-blockdiag/

Documentation

http://blockdiag.com/en/blockdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-blockdiag

Sphinx extension for embedding block diagrams using blockdiag.

Features

  1. Generate block-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Todo

activate “Block Diagram” extension.

Directive Body Diagram
.. blockdiag::

For more details, see sphinxcontrib-blockdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
5
6
7
.. blockdiag::
   :align: center

   blockdiag {
       A -> B -> C;
            B -> D;
   }

:which gives:

   .. include:: blockdiag-directive-body-example.rsti
Description Table
the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. blockdiag::
   :align: center
   :desctable:

   blockdiag {
       A -> B -> C;
       A [description = "browsers in each client"];
       B [description = "web server"];
       C [description = "database server"];
   }

:which gives:

   .. include:: blockdiag-description-table-example.rsti
Include Diagram
the example
1
2
3
4
.. blockdiag:: block.diag
   :caption: Style attributes to nodes and edges (Block Diagram example)
   :align: center
   :width: 640

:which gives:

   .. blockdiag:: block.diag
      :caption: Style attributes to nodes and edges (Block Diagram example)
      :align: center
      :width: 640
which needs

The example above comes from the original Sample diagrams web page and processed the following file content:

Block Diagram example file (block.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
blockdiag {
    // Set boder-style, backgroun-color and text-color to nodes.
    A [style = dotted];
    B [style = dashed];
    C [color = pink, style = "3,3,3,3,15,3"]; //dashed_array format style
    D [shape = circle, color = "#888888", textcolor="#FFFFFF"];

    // Set border-style and color to edges.
    A -> B [style = dotted];
    B -> C [style = dashed];
    C -> D [color = "red", style = "3,3,3,3,15,3"]; //dashed_array format style

    // Set numbered-badge to nodes.
    E [numbered = 99];

    // Set background image to nodes (and erase label).
    F [label = "", background = "https://github.com/sphinx-doc/sphinx/raw/master/doc/_static/sphinx.png"];
    G [label = "", background = "https://www.python.org/static/community_logos/python-logo-master-v3-TM.png"];
    H [icon = "https://github.com/blockdiag/blockdiag.com/raw/master/sources/en/_static/help-browser.png"];
    I [icon = "https://github.com/blockdiag/blockdiag.com/raw/master/sources/en/_static/internet-mail.png"];
    J [shape = actor]

    // Set arrow direction to edges.
    E -> F [dir = none, label = edge];
    F -> G [dir = forward];
    G -> H [dir = back];

    group {
        orientation = portrait;
        color = lightgray;
        H -> I [dir = both];
    }

    // Set width and height to nodes.
    K [width = 192]; // default value is 128
    L [shape = square, height = 64]; // default value is 40

    // Use thick line
    J -> K [thick]
    K -> L;
}

Sequence Diagram

sphinxcontrib-seqdiag is a Sphinx extension for embedding sequence diagrams. You can embed sequence diagrams with the .. seqdiag:: directive.

PyPI Package

https://pypi.org/project/sphinxcontrib-seqdiag/

Documentation

http://blockdiag.com/en/seqdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-seqdiag

Sphinx extension for embedding sequence diagrams using seqdiag.

Features

  1. Generate sequence-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Todo

activate “Sequence Diagram” extension.

Directive Body Diagram
.. seqdiag::

For more details, see sphinxcontrib-seqdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
.. seqdiag::
   :align: center

   seqdiag {
       # define order of elements
       # seqdiag sorts elements by order they appear
       browser; database; webserver;

       browser  -> webserver [label = "GET /index.html"];
       browser <-- webserver;
       browser  -> webserver [label = "POST /blog/comment"];
                   webserver  -> database [label = "INSERT comment"];
                   webserver <-- database;
       browser <-- webserver;
   }

:which gives:

   .. include:: seqdiag-directive-body-example.rsti
Description Table
the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. seqdiag::
   :align: center
   :desctable:

   seqdiag {
       A -> B -> C;
       A [description = "browsers in each client"];
       B [description = "web server"];
       C [description = "database server"];
   }

:which gives:

   .. include:: seqdiag-description-table-example.rsti
Include Diagram
the example
1
2
3
4
.. seqdiag:: seq.diag
   :caption: Style attributes to diagram and edges (Sequence Diagram example)
   :align: center
   :height: 640

:which gives:

   .. seqdiag:: seq.diag
      :caption: Style attributes to diagram and edges (Sequence Diagram example)
      :align: center
      :height: 640
which needs

The example above comes from the original Sample diagrams web page and processed the following file content:

Sequence Diagram example file (seq.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
seqdiag {
    // Set edge metrix.
    edge_length = 300;  // default value is 192
    span_height = 80;  // default value is 40

    // Set fontsize.
    default_fontsize = 16;  // default value is 11

    // Do not show activity line
    activation = none;

    // Numbering edges automaticaly
    autonumber = True;

    // Change note color
    default_note_color = lightgreen;

    browser  -> webserver [label = "GET \n/index.html"];
    browser <-- webserver [note = "Apache works!"];

    // Separator
    === Separator line ===

    // color of edge
    browser -> webserver [label = "misformatted", color = red];

    // failed edge
    browser -> webserver [label = "failed browser", failed];
}

Activity Diagram

sphinxcontrib-actdiag is a Sphinx extension for embedding activity diagrams. You can embed activity diagrams with the .. actdiag::` directive.

PyPI Package

https://pypi.org/project/sphinxcontrib-actdiag/

Documentation

http://blockdiag.com/en/actdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-actdiag

Sphinx extension for embedding activity diagrams using actdiag.

Features

  1. Generate activity-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Todo

activate “Activity Diagram” extension.

Directive Body Diagram
.. actdiag::

For more details, see sphinxcontrib-actdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
.. actdiag::
   :align: center
   :scale: 75

   actdiag {
        A -> B -> C -> D;

        lane foo {
             A; B;
        }
        lane bar {
             C; D;
        }
   }

:which gives:

   .. include:: actdiag-directive-body-example.rsti
Description Table
the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
.. actdiag::
   :align: center
   :scale: 75
   :desctable:

   actdiag {
        A -> B -> C;
        A [description = "browsers in each client"];
        B [description = "web server"];
        C [description = "database server"];
   }

:which gives:

   .. include:: actdiag-description-table-example.rsti
Include Diagram
the example
1
2
3
4
5
.. blockdiag:: act.diag
   :caption: Style attributes to frames and nodes (Activity Diagram example)
   :align: center
   :scale: 75
   :width: 640

:which gives:

   .. actdiag:: act.diag
      :caption: Style attributes to frames and nodes (Activity Diagram example)
      :align: center
      :scale: 75
      :width: 640
which needs

The example above comes from the original Sample diagrams web page and processed the following file content:

Activity Diagram example file (act.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
actdiag {
    write -> convert -> image;

    lane user {
         label = "User";
         write [label = "Writing reST"];
         image [label = "Get diagram IMAGE"];
    }
    lane actdiag {
         convert [label = "Convert reST to Image"];
    }
}

Network Diagram

sphinxcontrib-nwdiag is a Sphinx extension for embedding network diagrams. You can embed network diagrams with the .. nwdiag::, .. rackdiag:: and .. packetdiag:: directives.

PyPI Package

https://pypi.org/project/sphinxcontrib-nwdiag/

Documentation

http://blockdiag.com/en/nwdiag/sphinxcontrib.html

Git Repository

https://github.com/blockdiag/sphinxcontrib-nwdiag

Sphinx extension for embedding network diagrams using nwdiag.

Features

  1. Generate network-diagram from dot like text (basic feature).

  2. Multilingualism for node-label (utf-8 only).

Todo

activate “Network Diagram” extension.

Directive Body Diagram
.. nwdiag::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. nwdiag::
   :align: center
   :scale: 75

   nwdiag {
       network dmz {
           web01;
           web02;
       }
   }

:which gives:

   .. include:: nwdiag-directive-body-example.rsti
Description Table
the example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
.. nwdiag::
   :align: center
   :scale: 75
   :desctable:

   nwdiag {
       network dmz {
           web01 [address = "192.168.0.1", description = "web server01"];
           web02 [address = "192.168.0.2", description = "web server02"];
       }
       network internal {
           web01 [address = "172.0.0.1"];
           db01 [address = "172.0.0.2,172.0.0.20", description = "database server"];
       }
   }

:which gives:

   .. include:: nwdiag-description-table-example.rsti
Include Diagram
Network
the example
1
2
3
4
5
.. nwdiag:: nw.diag
   :caption: Peer networks and grouping nodes (Network Diagram example)
   :align: center
   :scale: 75
   :width: 640

:which gives:

   .. nwdiag:: nw.diag
      :caption: Peer networks and grouping nodes (Network Diagram example)
      :align: center
      :scale: 75
      :width: 640
which needs

The example above comes from the original Sample diagrams: nwdiag web page and processed the following file content:

Network Diagram example file (nw.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
nwdiag {
    inet [shape = cloud];
    inet -- router;

    network front {
        address = "192.168.0.0/24";
        router;
        web01;
        web02;

        // define network using defined nodes
        group db {
            web01;
            web02;
        }
    }
}
Rack
.. rack::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
.. rackdiag:: rack.diag
   :caption: Multiple racks with multiple and blocked units (Rack Diagram example)
   :align: center
   :height: 480

:which gives:

   .. rackdiag:: rack.diag
      :caption: Multiple racks with multiple and blocked units (Rack Diagram example)
      :align: center
      :height: 480
Which needs

The example above comes from the original Sample diagrams: rackdiag web page and processed the following file content:

Rack Diagram example file (rack.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
rackdiag {
    default_fontsize = 10;

    // define 1st (height) rack
    rack {
        16U;

        // define rack items
        1: UPS [2U, fontsize = 14];
        3: DB Server;
        // put 2 units to rack-level 4
        4: Web\nServer 1;
        4: Web\nServer 2;
        5: Web\nServer 3;
        5: Web\nServer 4;
        7: Load Balancer;
        8: L3 Switch;
    }

    // define 2nd rack
    rack {
        12U;

        // define rack items
        1: UPS [2U, fontsize = 14];
        3: DB Server;
        4: Web Server;
        5: Web Server;
        6: Web Server;
        7: Load Balancer;
        8: L3 Switch;
    }

    // define 3rd rack (with not available units)
    rack {
        12U;

        1: Server;
        2: Server;
        3: Server;
        4: Server;
        5: N/A [8U, fontsize = 14];
    }
}
Packet
.. packet::

For more details, see sphinxcontrib-nwdiag in the extension demonstration and the README.rst in the extension Git repository.

The example
1
2
3
4
.. packetdiag:: packet.diag
   :caption: Structure of TCP Header (Packet Diagram example)
   :align: center
   :width: 640

:which gives:

   .. packetdiag:: packet.diag
      :caption: Structure of TCP Header (Packet Diagram example)
      :align: center
      :width: 640
Which needs

The example above comes from the original Sample diagrams: packetdiag web page and processed the following file content:

Packet Diagram example file (packet.diag)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
packetdiag {
    colwidth = 32;
    node_height = 40;
    default_fontsize = 12;

    0-15: Source Port;
    16-31: Destination Port;
    32-63: Sequence Number;
    64-95: Acknowledgment Number;
    96-99: Data\nOffset;
    100-105: Reserved;
    106: URG [rotate = 270];
    107: ACK [rotate = 270];
    108: PSH [rotate = 270];
    109: RST [rotate = 270];
    110: SYN [rotate = 270];
    111: FIN [rotate = 270];
    112-127: Window;
    128-143: Checksum;
    144-159: Urgent Pointer;
    160-191: (Options and Padding);
    192-223: Data [colheight = 3];
}

Tabbed Content

Attention

Only practicable and usable for HTML builder.

PyPI Package

https://pypi.org/project/sphinx-tabs/

Documentation

https://sphinx-tabs.readthedocs.io/

Git Repository

https://github.com/executablebooks/sphinx-tabs

Create tabbed content in Sphinx documentation when building HTML.

Features

  1. Basic and nested tabs.

  2. Grouped Tabs.

  3. Code Tabs.

Todo

activate “Tabbed Content” extension.

.. tabs::
.. tab::

For more details, see Simple Tabs in the extension demonstration and the README.md in the extension Git repository.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
.. tabs::

   .. tab:: **Apples**

      Apples are green, or sometimes red.

   .. tab:: **Pears**

      Pears are green.

   .. tab:: **Oranges**

      Oranges are orange.

:which gives:

   .. include:: sphinx-tabs-example.rsti

Nested tabs are also possible.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
.. tabs::

   .. tab:: Stars

      .. tabs::

         .. tab:: The Sun

            The closest star to us.

         .. tab:: Proxima Centauri

            The second closest star to us.

         .. tab:: Polaris

            The North Star.

   .. tab:: Moons

      .. tabs::

         .. tab:: The Moon

            Orbits the Earth

         .. tab:: Titan

            Orbits Jupiter

:which gives:

   .. include:: sphinx-tabs-nested-example.rsti
.. group-tab::

Also tabs can stick together in groups.

The example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
.. rubric:: operating systems

.. tabs::

   .. group-tab:: Linux

      **Linux** is Unix-like, but was developed without any Unix code.
      The Linux kernel originated in 1991, as a project of Linus
      Torvalds, while a university student in Finland.

   .. group-tab:: Mac OS X

      **Mac OS X** is a line of open core graphical operating systems
      developed, marketed, and sold by Apple Inc.

   .. group-tab:: Microsoft Windows

      **Microsoft Windows** is a family of proprietary operating systems
      designed by Microsoft Corporation and primarily targeted to
      Intel architecture based computers.

.. rubric:: integrated development environments

.. tabs::

   .. group-tab:: Linux

      **There is no dedicated or default integrated development
      environment (IDE)** on *Linux*. `Here is a list`_ of IDEs
      which will run natively on *Linux*.

   .. group-tab:: Mac OS X

      **Xcode** is an integrated development environment (IDE) for
      *Mac OS X* containing a suite of software development tools
      developed by Apple Inc.

   .. group-tab:: Microsoft Windows

      **Microsoft Visual Studio** is an integrated development
      environment (IDE) from Microsoft Corporation. It is used to
      develop computer programs uses Microsoft software development
      platforms such as *Windows API*, *Windows Forms*, *Windows
      Presentation Foundation*, *Windows Store* and *Microsoft
      Silverlight*.

.. _`Here is a list`:
   https://en.wikipedia.org/wiki/Category:Linux_integrated_development_environments

:which gives:

   .. include:: sphinx-tabs-group-example.rsti

Paneled Content

Attention

Only practicable and usable for HTML builder.

PyPI Package

https://pypi.org/project/sphinx-panels/

Documentation

https://sphinx-panels.readthedocs.io/

Git Repository

https://github.com/executablebooks/sphinx-panels

Create paneled content in Sphinx documentation when building HTML.

Features

  1. Panels in grid or cards layout.

  2. Panels with click-able link-button.

  3. Panels with toggle-able content by drop-downs.

  4. Panels with styling: header, footer, images, icons, badges, animations

For more details, see sphinx-panels in the extension demonstration and the README.md in the extension Git repository.

Todo

activate “Paneled Content” extension.

.. panels::

For more details, see Panels Usage.

.. dropdown::

For more details, see Dropdown Usage.

For more details, see Link Buttons.

.. div::

For more details, see Div Directive.

:badge:

For more details, see Link Badges.

:opticon:
:fa:

For more details, see Inline Icons.

Extension not applicable

This Sphinx extension is quite new and is under constant development. The current behavior disturbs the integration, so the extension is disabled for now (see conf.py). Currently known bugs are:

  • annoying side effects with the Tabbed Content extension by the automatically integrated and delivered Bootstrap 4.0 CSS

  • no proper and practical LaTeX builder support

Email Obfuscate

Attention

Only practicable and usable for HTML builder.

PyPI Package

https://pypi.org/project/sphinxcontrib-email/

Documentation

https://github.com/sphinx-contrib/email/blob/master/README.rst

Git Repository

https://github.com/sphinx-contrib/email

Python 3 Fixes

https://github.com/rexut/sphinxcontrib-email/tree/python3-fixes

Todo

activate “Email Obfuscate” extension.

To obfuscate an email address use something like:

:email:`Name Surname <user@myplace.org>`
:email:`Name Surname (user@myplace.org)`

That renders as Name Surname with the appropriate mailto link.

:email:`user@myplace.org`

That renders as user@myplace.org with the appropriate mailto link.

:email:
The example
1
2
3
* :email:`Name Surname <user@myplace.org>`
* :email:`Name Surname (user@myplace.org)`
* :email:`user@myplace.org`

:which gives:

   .. include:: email-example.rsti

Themes

Section author: Stephan Linz <linz@li-pro.net>

Let’s decorate the project documentation. There are a lot of themes for the Sphinx HTML builder available on the Sphinx Themes Demo Page.

This documentation use the Read the Docs Sphinx Theme as demonstrate at the Sphinx RTD Theme Demo Page.

Another interesting and actively developed theme is The Sphinx Book Theme, the theme by The Executable Book Project.

Read the Docs Sphinx Theme

PyPI Package

https://pypi.org/project/sphinx-rtd-theme/

Documentation

https://sphinx-rtd-theme.readthedocs.io/

Git Repository

https://github.com/readthedocs/sphinx_rtd_theme

This theme is primarily focused to be used on Read the Docs but can work with your own sphinx projects. You can find a working demo of the theme in the theme documentation.

screen_desktop.png

Sphinx RTD theme on Desktop
screen_mobile.png

Sphinx RTD theme on Mobiles

Cheat Sheet

Section author: Stephan Linz <linz@li-pro.net>

We have made a cheat sheet for helping you remember the syntax for reStructuredText & Sphinx programs. The basic reStructuredText Cheat Sheet could also be very helpful.

Cheat Sheet reStructuredText & Sphinx 1/2

Cheat Sheet reStructuredText & Sphinx 1/2

Cheat Sheet reStructuredText & Sphinx 2/2

Cheat Sheet reStructuredText & Sphinx 2/2

Appendix

Section author: Stephan Linz <linz@li-pro.net>

License

License text of the Li-Pro.Net Sphinx Primer
Creative Commons Legal Code

Attribution-ShareAlike 3.0 Unported

    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
    LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN
    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
    REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR
    DAMAGES RESULTING FROM ITS USE.

License

THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE
COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY
COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS
AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE
TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY
BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS
CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND
CONDITIONS.

1. Definitions

 a. "Adaptation" means a work based upon the Work, or upon the Work and
    other pre-existing works, such as a translation, adaptation,
    derivative work, arrangement of music or other alterations of a
    literary or artistic work, or phonogram or performance and includes
    cinematographic adaptations or any other form in which the Work may be
    recast, transformed, or adapted including in any form recognizably
    derived from the original, except that a work that constitutes a
    Collection will not be considered an Adaptation for the purpose of
    this License. For the avoidance of doubt, where the Work is a musical
    work, performance or phonogram, the synchronization of the Work in
    timed-relation with a moving image ("synching") will be considered an
    Adaptation for the purpose of this License.
 b. "Collection" means a collection of literary or artistic works, such as
    encyclopedias and anthologies, or performances, phonograms or
    broadcasts, or other works or subject matter other than works listed
    in Section 1(f) below, which, by reason of the selection and
    arrangement of their contents, constitute intellectual creations, in
    which the Work is included in its entirety in unmodified form along
    with one or more other contributions, each constituting separate and
    independent works in themselves, which together are assembled into a
    collective whole. A work that constitutes a Collection will not be
    considered an Adaptation (as defined below) for the purposes of this
    License.
 c. "Creative Commons Compatible License" means a license that is listed
    at https://creativecommons.org/compatiblelicenses that has been
    approved by Creative Commons as being essentially equivalent to this
    License, including, at a minimum, because that license: (i) contains
    terms that have the same purpose, meaning and effect as the License
    Elements of this License; and, (ii) explicitly permits the relicensing
    of adaptations of works made available under that license under this
    License or a Creative Commons jurisdiction license with the same
    License Elements as this License.
 d. "Distribute" means to make available to the public the original and
    copies of the Work or Adaptation, as appropriate, through sale or
    other transfer of ownership.
 e. "License Elements" means the following high-level license attributes
    as selected by Licensor and indicated in the title of this License:
    Attribution, ShareAlike.
 f. "Licensor" means the individual, individuals, entity or entities that
    offer(s) the Work under the terms of this License.
 g. "Original Author" means, in the case of a literary or artistic work,
    the individual, individuals, entity or entities who created the Work
    or if no individual or entity can be identified, the publisher; and in
    addition (i) in the case of a performance the actors, singers,
    musicians, dancers, and other persons who act, sing, deliver, declaim,
    play in, interpret or otherwise perform literary or artistic works or
    expressions of folklore; (ii) in the case of a phonogram the producer
    being the person or legal entity who first fixes the sounds of a
    performance or other sounds; and, (iii) in the case of broadcasts, the
    organization that transmits the broadcast.
 h. "Work" means the literary and/or artistic work offered under the terms
    of this License including without limitation any production in the
    literary, scientific and artistic domain, whatever may be the mode or
    form of its expression including digital form, such as a book,
    pamphlet and other writing; a lecture, address, sermon or other work
    of the same nature; a dramatic or dramatico-musical work; a
    choreographic work or entertainment in dumb show; a musical
    composition with or without words; a cinematographic work to which are
    assimilated works expressed by a process analogous to cinematography;
    a work of drawing, painting, architecture, sculpture, engraving or
    lithography; a photographic work to which are assimilated works
    expressed by a process analogous to photography; a work of applied
    art; an illustration, map, plan, sketch or three-dimensional work
    relative to geography, topography, architecture or science; a
    performance; a broadcast; a phonogram; a compilation of data to the
    extent it is protected as a copyrightable work; or a work performed by
    a variety or circus performer to the extent it is not otherwise
    considered a literary or artistic work.
 i. "You" means an individual or entity exercising rights under this
    License who has not previously violated the terms of this License with
    respect to the Work, or who has received express permission from the
    Licensor to exercise rights under this License despite a previous
    violation.
 j. "Publicly Perform" means to perform public recitations of the Work and
    to communicate to the public those public recitations, by any means or
    process, including by wire or wireless means or public digital
    performances; to make available to the public Works in such a way that
    members of the public may access these Works from a place and at a
    place individually chosen by them; to perform the Work to the public
    by any means or process and the communication to the public of the
    performances of the Work, including by public digital performance; to
    broadcast and rebroadcast the Work by any means including signs,
    sounds or images.
 k. "Reproduce" means to make copies of the Work by any means including
    without limitation by sound or visual recordings and the right of
    fixation and reproducing fixations of the Work, including storage of a
    protected performance or phonogram in digital form or other electronic
    medium.

2. Fair Dealing Rights. Nothing in this License is intended to reduce,
limit, or restrict any uses free from copyright or rights arising from
limitations or exceptions that are provided for in connection with the
copyright protection under copyright law or other applicable laws.

3. License Grant. Subject to the terms and conditions of this License,
Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
perpetual (for the duration of the applicable copyright) license to
exercise the rights in the Work as stated below:

 a. to Reproduce the Work, to incorporate the Work into one or more
    Collections, and to Reproduce the Work as incorporated in the
    Collections;
 b. to create and Reproduce Adaptations provided that any such Adaptation,
    including any translation in any medium, takes reasonable steps to
    clearly label, demarcate or otherwise identify that changes were made
    to the original Work. For example, a translation could be marked "The
    original work was translated from English to Spanish," or a
    modification could indicate "The original work has been modified.";
 c. to Distribute and Publicly Perform the Work including as incorporated
    in Collections; and,
 d. to Distribute and Publicly Perform Adaptations.
 e. For the avoidance of doubt:

     i. Non-waivable Compulsory License Schemes. In those jurisdictions in
        which the right to collect royalties through any statutory or
        compulsory licensing scheme cannot be waived, the Licensor
        reserves the exclusive right to collect such royalties for any
        exercise by You of the rights granted under this License;
    ii. Waivable Compulsory License Schemes. In those jurisdictions in
        which the right to collect royalties through any statutory or
        compulsory licensing scheme can be waived, the Licensor waives the
        exclusive right to collect such royalties for any exercise by You
        of the rights granted under this License; and,
   iii. Voluntary License Schemes. The Licensor waives the right to
        collect royalties, whether individually or, in the event that the
        Licensor is a member of a collecting society that administers
        voluntary licensing schemes, via that society, from any exercise
        by You of the rights granted under this License.

The above rights may be exercised in all media and formats whether now
known or hereafter devised. The above rights include the right to make
such modifications as are technically necessary to exercise the rights in
other media and formats. Subject to Section 8(f), all rights not expressly
granted by Licensor are hereby reserved.

4. Restrictions. The license granted in Section 3 above is expressly made
subject to and limited by the following restrictions:

 a. You may Distribute or Publicly Perform the Work only under the terms
    of this License. You must include a copy of, or the Uniform Resource
    Identifier (URI) for, this License with every copy of the Work You
    Distribute or Publicly Perform. You may not offer or impose any terms
    on the Work that restrict the terms of this License or the ability of
    the recipient of the Work to exercise the rights granted to that
    recipient under the terms of the License. You may not sublicense the
    Work. You must keep intact all notices that refer to this License and
    to the disclaimer of warranties with every copy of the Work You
    Distribute or Publicly Perform. When You Distribute or Publicly
    Perform the Work, You may not impose any effective technological
    measures on the Work that restrict the ability of a recipient of the
    Work from You to exercise the rights granted to that recipient under
    the terms of the License. This Section 4(a) applies to the Work as
    incorporated in a Collection, but this does not require the Collection
    apart from the Work itself to be made subject to the terms of this
    License. If You create a Collection, upon notice from any Licensor You
    must, to the extent practicable, remove from the Collection any credit
    as required by Section 4(c), as requested. If You create an
    Adaptation, upon notice from any Licensor You must, to the extent
    practicable, remove from the Adaptation any credit as required by
    Section 4(c), as requested.
 b. You may Distribute or Publicly Perform an Adaptation only under the
    terms of: (i) this License; (ii) a later version of this License with
    the same License Elements as this License; (iii) a Creative Commons
    jurisdiction license (either this or a later license version) that
    contains the same License Elements as this License (e.g.,
    Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible
    License. If you license the Adaptation under one of the licenses
    mentioned in (iv), you must comply with the terms of that license. If
    you license the Adaptation under the terms of any of the licenses
    mentioned in (i), (ii) or (iii) (the "Applicable License"), you must
    comply with the terms of the Applicable License generally and the
    following provisions: (I) You must include a copy of, or the URI for,
    the Applicable License with every copy of each Adaptation You
    Distribute or Publicly Perform; (II) You may not offer or impose any
    terms on the Adaptation that restrict the terms of the Applicable
    License or the ability of the recipient of the Adaptation to exercise
    the rights granted to that recipient under the terms of the Applicable
    License; (III) You must keep intact all notices that refer to the
    Applicable License and to the disclaimer of warranties with every copy
    of the Work as included in the Adaptation You Distribute or Publicly
    Perform; (IV) when You Distribute or Publicly Perform the Adaptation,
    You may not impose any effective technological measures on the
    Adaptation that restrict the ability of a recipient of the Adaptation
    from You to exercise the rights granted to that recipient under the
    terms of the Applicable License. This Section 4(b) applies to the
    Adaptation as incorporated in a Collection, but this does not require
    the Collection apart from the Adaptation itself to be made subject to
    the terms of the Applicable License.
 c. If You Distribute, or Publicly Perform the Work or any Adaptations or
    Collections, You must, unless a request has been made pursuant to
    Section 4(a), keep intact all copyright notices for the Work and
    provide, reasonable to the medium or means You are utilizing: (i) the
    name of the Original Author (or pseudonym, if applicable) if supplied,
    and/or if the Original Author and/or Licensor designate another party
    or parties (e.g., a sponsor institute, publishing entity, journal) for
    attribution ("Attribution Parties") in Licensor's copyright notice,
    terms of service or by other reasonable means, the name of such party
    or parties; (ii) the title of the Work if supplied; (iii) to the
    extent reasonably practicable, the URI, if any, that Licensor
    specifies to be associated with the Work, unless such URI does not
    refer to the copyright notice or licensing information for the Work;
    and (iv) , consistent with Ssection 3(b), in the case of an
    Adaptation, a credit identifying the use of the Work in the Adaptation
    (e.g., "French translation of the Work by Original Author," or
    "Screenplay based on original Work by Original Author"). The credit
    required by this Section 4(c) may be implemented in any reasonable
    manner; provided, however, that in the case of a Adaptation or
    Collection, at a minimum such credit will appear, if a credit for all
    contributing authors of the Adaptation or Collection appears, then as
    part of these credits and in a manner at least as prominent as the
    credits for the other contributing authors. For the avoidance of
    doubt, You may only use the credit required by this Section for the
    purpose of attribution in the manner set out above and, by exercising
    Your rights under this License, You may not implicitly or explicitly
    assert or imply any connection with, sponsorship or endorsement by the
    Original Author, Licensor and/or Attribution Parties, as appropriate,
    of You or Your use of the Work, without the separate, express prior
    written permission of the Original Author, Licensor and/or Attribution
    Parties.
 d. Except as otherwise agreed in writing by the Licensor or as may be
    otherwise permitted by applicable law, if You Reproduce, Distribute or
    Publicly Perform the Work either by itself or as part of any
    Adaptations or Collections, You must not distort, mutilate, modify or
    take other derogatory action in relation to the Work which would be
    prejudicial to the Original Author's honor or reputation. Licensor
    agrees that in those jurisdictions (e.g. Japan), in which any exercise
    of the right granted in Section 3(b) of this License (the right to
    make Adaptations) would be deemed to be a distortion, mutilation,
    modification or other derogatory action prejudicial to the Original
    Author's honor and reputation, the Licensor will waive or not assert,
    as appropriate, this Section, to the fullest extent permitted by the
    applicable national law, to enable You to reasonably exercise Your
    right under Section 3(b) of this License (right to make Adaptations)
    but not otherwise.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR
OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY
KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE,
INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY,
FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF
LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS,
WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION
OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE
LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR
ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES
ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination

 a. This License and the rights granted hereunder will terminate
    automatically upon any breach by You of the terms of this License.
    Individuals or entities who have received Adaptations or Collections
    from You under this License, however, will not have their licenses
    terminated provided such individuals or entities remain in full
    compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will
    survive any termination of this License.
 b. Subject to the above terms and conditions, the license granted here is
    perpetual (for the duration of the applicable copyright in the Work).
    Notwithstanding the above, Licensor reserves the right to release the
    Work under different license terms or to stop distributing the Work at
    any time; provided, however that any such election will not serve to
    withdraw this License (or any other license that has been, or is
    required to be, granted under the terms of this License), and this
    License will continue in full force and effect unless terminated as
    stated above.

8. Miscellaneous

 a. Each time You Distribute or Publicly Perform the Work or a Collection,
    the Licensor offers to the recipient a license to the Work on the same
    terms and conditions as the license granted to You under this License.
 b. Each time You Distribute or Publicly Perform an Adaptation, Licensor
    offers to the recipient a license to the original Work on the same
    terms and conditions as the license granted to You under this License.
 c. If any provision of this License is invalid or unenforceable under
    applicable law, it shall not affect the validity or enforceability of
    the remainder of the terms of this License, and without further action
    by the parties to this agreement, such provision shall be reformed to
    the minimum extent necessary to make such provision valid and
    enforceable.
 d. No term or provision of this License shall be deemed waived and no
    breach consented to unless such waiver or consent shall be in writing
    and signed by the party to be charged with such waiver or consent.
 e. This License constitutes the entire agreement between the parties with
    respect to the Work licensed here. There are no understandings,
    agreements or representations with respect to the Work not specified
    here. Licensor shall not be bound by any additional provisions that
    may appear in any communication from You. This License may not be
    modified without the mutual written agreement of the Licensor and You.
 f. The rights granted under, and the subject matter referenced, in this
    License were drafted utilizing the terminology of the Berne Convention
    for the Protection of Literary and Artistic Works (as amended on
    September 28, 1979), the Rome Convention of 1961, the WIPO Copyright
    Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996
    and the Universal Copyright Convention (as revised on July 24, 1971).
    These rights and subject matter take effect in the relevant
    jurisdiction in which the License terms are sought to be enforced
    according to the corresponding provisions of the implementation of
    those treaty provisions in the applicable national law. If the
    standard suite of rights granted under applicable copyright law
    includes additional rights not granted under this License, such
    additional rights are deemed to be included in the License; this
    License is not intended to restrict the license of any rights under
    applicable law.


Creative Commons Notice

    Creative Commons is not a party to this License, and makes no warranty
    whatsoever in connection with the Work. Creative Commons will not be
    liable to You or any party on any legal theory for any damages
    whatsoever, including without limitation any general, special,
    incidental or consequential damages arising in connection to this
    license. Notwithstanding the foregoing two (2) sentences, if Creative
    Commons has expressly identified itself as the Licensor hereunder, it
    shall have all rights and obligations of Licensor.

    Except for the limited purpose of indicating to the public that the
    Work is licensed under the CCPL, Creative Commons does not authorize
    the use by either party of the trademark "Creative Commons" or any
    related trademark or logo of Creative Commons without the prior
    written consent of Creative Commons. Any permitted use will be in
    compliance with Creative Commons' then-current trademark usage
    guidelines, as may be published on its website or otherwise made
    available upon request from time to time. For the avoidance of doubt,
    this trademark restriction does not form part of the License.

    Creative Commons may be contacted at https://creativecommons.org/.

Credits

Authors cited when creating the Li-Pro.Net Sphinx Primer
___________________________________________________________________________

AUTHORS (in alphabetical order)
___________________________________________________________________________

Armin Ronacher <armin.ronacher@active-4.com>  Sphinx Code and Documentation
Bareos GmbH & Co. KG <info@bareos.org>        Bareos Documentation
David Goodger <goodger@python.org>            Docutils and reStructuredText
Eric Holscher <eric@ericholscher.com>         Sphinx Tutorial
Georg Brandl <georg@python.org>               Sphinx Code and Documentation
Richard Jones <rjones@ekit-inc.com>           ReStructuredText Primer
Stephan Linz <linz@li-pro.net>                Li-Pro.Net Sphinx Primer
___________________________________________________________________________

Glossary

Section author: Stephan Linz <linz@li-pro.net>

Terms

Commons

Docutils

Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML, LaTeX, man-pages, open-document or XML. It includes reStructuredText, the easy to read, easy to use, what-you-see-is-what-you-get plaintext markup language.

See also

LaTeX

LaTeX is a document preparation system for high-quality typesetting. It is most often used for medium-to-large technical or scientific documents but it can be used for almost any form of publishing. LaTeX uses the TeX typesetting program for formatting its output, and is itself written in the TeX macro language.

See also

PyEnchant

PyEnchant is a Python binding for Enchant.

reStructuredText

reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation. It is part of the Docutils project of the Python Doc-SIG (Documentation Special Interest Group)

See also

Sphinx

Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments. Sphinx converts reStructuredText files into HTML websites and other formats including PDF, EPub, Texinfo and man.

reStructuredText is extensible, and Sphinx exploits its extensible nature through a number of extensions–for autogenerating documentation from source code, writing mathematical notation or highlighting source code, etc.

See also

Technologies

BibTeX

BibTeX is a widely used bibliography management tool in LaTeX, with BibTeX the bibliography entries are kept in a separate file and then imported into the main document.

See also

Enchant

Enchant is a free software project developed as part of the AbiWord word processor with the aim of unifying access to the various existing spell-checker software.

See also

PGF
TikZ
PGF/TikZ

PGF/TikZ is a pair of languages for producing vector graphics (for example: technical illustrations and drawings) from a geometric/algebraic description, with standard features including the drawing of points, lines, arrows, paths, circles, ellipses and polygons. PGF, the Portable Graphic Format, is a lower-level language, while TikZ, which is written in TeX, is a set of higher-level macros that use PGF.

TeX

TeX is a computer language designed for use in typesetting system; in particular, for typesetting math and other technical material. It has been noted as one of the most sophisticated digital typographical systems and is also used for many other typesetting tasks, especially in the form of LaTeX, ConTeXt, and other macro packages.

Listings

Note

Listings is not supported for HTML.

List of Tables

Note

List of Tables is not supported for HTML.

List of Figures

Note

List of Figures is not supported for HTML.

List of Equations

Note

List of Equations is not supported for HTML.

List of Downloads

Legal Notice of Li-Pro.Net Sphinx Primer

All artifacts were selected and download by using this reference URLs:

List of Issues (To-Do)

Todo

activate “BibTeX Citations” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/bibtex.rst, line 28.)

Todo

activate “Block Diagram Family” extensions.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/blockdiag.rst, line 9.)

Todo

activate “Activity Diagram” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/blockdiag/actdiag.rst, line 25.)

Todo

activate “Block Diagram” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/blockdiag/blockdiag.rst, line 25.)

Todo

activate “Network Diagram” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/blockdiag/nwdiag.rst, line 25.)

Todo

activate “Sequence Diagram” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/blockdiag/seqdiag.rst, line 25.)

Todo

activate “Email Obfuscate” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/email.rst, line 18.)

Todo

activate “LinuxDoc” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/linuxdoc.rst, line 22.)

Todo

activate “Mathematical Plots” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/matplotlib.rst, line 30.)

Todo

activate “Program Output” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/programoutput.rst, line 18.)

Todo

activate “Paneled Content” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/sphinx-panels.rst, line 29.)

Todo

activate “Tabbed Content” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/sphinx-tabs.rst, line 25.)

Todo

activate “PGF/TikZ LaTeX Pictures” extension.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/lpn-doc-sphinx-primer/checkouts/0.0.3/source/extensions/tikz.rst, line 39.)

Bibliography

juh2019swdocwspx

Jan Ulrich Hasecke. Software-Dokumentation mit Sphinx. CreateSpace (was part of Amazon.com Inc.), today Kindle Direct Publishing (KDP), Seattle, United States of America, 2. edition, 2019. ISBN 1793008779. ISBN-10: 1-79300-877-9, ISBN-13: 978-1793008770, OCLC: 889425279, URL: https://www.amazon.com/dp/1793008779 (March 2020).

Version history

Li-Pro.Net Sphinx Primer Document Revisions

Version

Change

Passed

Date

0.0.3

initial content in chapters “Extensions”

Stephan Linz

2020-09-11

0.0.2

initial content in chapters “Cheat Sheet” and “Themes”

Stephan Linz

2020-09-08

0.0.1

base document skeleton

Stephan Linz

2020-09-08

0.0

preliminary, project created

Stephan Linz

2020-09-05