3. Figures

For best results, figures, tables and code blocks should get captions and they should be referenced with and :xref: for figures/tables/code-blocks (:sref: for sections). :xref: and :sref: are defined as :numref:, when appropriate, otherwise as :ref:. Do not use the image directive to keep figures in place.

See figure 3.1 in section 3.1.4, Directive uml.

3.1. Figures with numbers

Sphinx allows certain entities to be referenced by number. This requires the option numfig to be set to True in conf.py as shown in listing 3.1.

listing 3.1 option numfig in conf.py
1
2
3
4
5
6
7
numfig = True
numfig_format = {
    'section': 'section {number}, {name}',
    'figure': 'figure %s',
    'table': 'table %s',
    'code-block': 'listing %s',
}

The supported entities are:

3.1.1. Directive figure

As documented.

  • always use fig: prefix for label

3.1.2. Directive table

The body must contain a table, however, a single table cell (rectangle) is sufficient (see listing 3.2 and table 3.1).

  • always use tab: prefix for label
listing 3.2 table directive with single table cell (rectangle)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
.. _`tab:single-cell`:
.. table:: single table cell (rectangle)

   +-----------------------+
   | .. code-block:: text  |
   |                       |
   |    code-block without |
   |    caption inside a   |
   |    single table cell  |
   +-----------------------+
table 3.1 single table cell (rectangle)
code-block without
caption inside a
single table cell

3.1.3. Directive code-block

code-block directives with a :caption: option can be referenced by number, e.g., “See :xref:`lst:cb-general`”: renders as “See listing 3.3”.

  • always use lst: prefix for label
  • always specify language
  • always use option :linenos:
listing 3.3 Definition of a general code-block listing
1
2
3
4
5
6
.. _`lst:<LABEL>`:
.. code-block:: <LANGUAGE>
   :caption: <TITLE>
   :linenos:

   <BODY>

An example is shown in listing 3.4.

listing 3.4 Example with Elisp code
1
2
3
4
5
6
7
8
.. _`lst:elisp-code`:
.. code-block:: elisp
   :caption: Some Emacs Lisp code
   :linenos:

   (if (not nil)
      (let (x) (princ x))
     (let(y) princ y))

The rendered example is shown in listing 3.5.

listing 3.5 Some Emacs Lisp code
1
2
3
(if (not nil)
   (let (x) (princ x))
  (let(y) princ y))

3.1.4. Directive uml

The uml directive for plantuml(1) diagrams also works as figure, as shown in listing 3.6 and figure 3.1.

  • always use fig: prefix for label
listing 3.6 uml directive for plantuml(1) diagrams
1
2
3
4
5
6
7
8
.. _`fig:uml-test`:
.. uml::
   :caption: UML test

   @startuml
   A --> B : send
   A <-- B : receive
   @enduml

@startuml
A --> B : send
A <-- B : receive
@enduml

figure 3.1 UML test

3.1.5. Directives graphviz, dot

Obviously, the graphviz directive for dot(1) diagrams also works as figure, as shown in listing 3.7 and figure 3.2.

  • always use fig: prefix for label
listing 3.7 graphviz directive for dot(1) graph diagrams
1
2
3
4
5
6
7
.. _`fig:dot-test`:
.. graphviz::
   :caption: dot test

   digraph xx {
   A -> B;
   }

digraph xx { A -> B; }

figure 3.2 dot test

3.1.6. Directive figctr

Since single cell tables end up in the table namespace, the extension ws_figure_container provides the figctr directive, which works like a container in the figure namespace (see listing 3.8 and figure 3.3).

listing 3.8 figctr directive
.. figctr:: Fig Ctr Caption

   Arbitrary things like this:

   .. code-block:: sh

      if test -r "file"
      then
          cat "file"
      fi

Arbitrary things like this:

if test -r "file"
then
    cat "file"
fi

figure 3.3 Fig Ctr Caption