Li-Pro.Net Sphinx Primer¶

Indentation¶

Indentation is meaningful in Sphinx and reStructuredText text. Usually, indenting a section means that is “belongs to” the line it is indented under.

for example

1 2 3 4

.. figure:: path-to-image.* This is the caption of the figure. Notice that it is indented under the line defining the figure.

The rules for indentation are:

• Use spaces, not tabs.

• Generally, indent three (3) spaces.

• Code example, indent four (4) spaces, except reStructuredText examples.

The exception to the three (3) spaces rule is Unordered (bullet) Lists and Ordered (numbered) Lists, where indentation follows the content of the list item.

unordered (bulleted) list

(2) spaces

1 2 3 4 5 6 7 8 9 10 11

* This is a list item. This is some additional content related to first item. Notice that it is indented to the same column as the first line of content. In this case, that's three (2) spaces. . . . * The N-th item in a list.

ordered (numbered) list

(4) spaces

1 2 3 4 5 6 7 8 9 10 11 12 13

1. This is a list item. This is some additional content related to Item 1. Notice that it is indented to the same column as the first line of content. In this case, that's three (3) spaces. . . . 10. The tenth item in a list. This related content will be indented four (4) spaces.

Sidebar navigation menu¶

The index.rst file serves as a front-page to the documentation and contains the main tables of content, defined using .. toctree:: directives. These .. toctree:: directives control the sidebar navigation menu. To add a new document to a table of content, add the file name (without the .rst extension) to the relevant list of file names in index.rst or any other (but only one) “sub-TOC trees”.

Secondary sub-TOC trees¶

Collections of documents are mostly given their own table of content on an individual page (see, for example: Appendix and Glossary). In these cases, the page containing the .. toctree:: serves as a sort of intro page for the collection. That intro must, itself, be included in the Sidebar navigation menu. The contents of a .. toctree:: appear as section links in another .. toctree:: it is included in. That is, if a .. toctree:: in index.rst lists .. glossary::, and glossary.rst has a .. toctree::, then the contents of that second .. toctree:: will appear in the Sidebar navigation menu, as sub-items to Glossary.

Indeed, this is precisely the case in this Li-Pro.Net Sphinx Primer document currently.

How this document uses main and secondary TOC¶

• Major topics get a .. toctree:: in index.rst

  Major topics include things like:

  • Each major parts (Extensions, Themes,…)

  • Large, general categories like Releases, Contributing, or Building

  Major topic tables of content include both sub-collection intro pages and also individual pages that don’t fit into a sub-collection.

  The :caption: attribute of the .. toctree:: directive may but not must defines the section label in the Sidebar navigation menu.

• Within a large topic, documents are grouped into collections of related pages, defined by a .. toctree:: on a topic intro page.

  Intro pages (pages that contain secondary .. toctree:: directives) may include additional content, introducing the collection or providing contextual way-finding. However, this is not always necessary or desirable. Use your judgment, and avoid stating things just for the sake of having some text. (“Here are the pages in this collection.”)

  We also (very occasionally) include .. toctree:: directives in sub-collection pages, such as:

  • BibTeX Citations,

  • Spelling Checker,

  • …

  • Read the Docs Sphinx Theme,

  • …

Tip

If it not obvious where a new document should appear in the navigation, the best practice is to simply ask about it in the GitHub issue driving the new page.

Note

For way-finding purposes, we sometimes create an Unordered (bullet) Lists of page links rather than a .. toctree:: directive (for example, see index.rst). We do this when using a .. toctree:: would create redundant links in the Sidebar navigation menu.

Quotes (block quotation) Element¶

Block quoted paragraphs are quoted by just indenting them more than the surrounding paragraphs.

the example

1 2 3 4 5 6 7 8 9

This line is not a block quote. Block quotes are indented, and otherwise unadorned. This is a block quote. --Adam Michael Wood - `Technical Content Writer`_ .. _`Technical Content Writer`: http://adammichaelwood.com/portfolio/

which gives

This line is not a block quote. Block quotes are indented, and otherwise unadorned.

This is a block quote.

—Adam Michael Wood - Technical Content Writer

.. pull-quote::¶

Pull-quoted paragraphs are similar to blockquotes but are directives for small selection of text to “pull out and quote”, typically in a larger typeface.

The example

1 2 3 4 5 6 7 8 9 10 11

This line is not a pull quote. Pull quotes are directive content. .. pull-quote:: This is a pull quote. --Adam Michael Wood - `Technical Content Writer`_ .. _`Technical Content Writer`: http://adammichaelwood.com/portfolio/

Which gives

This line is not a pull quote. Pull quotes are directive content.

This is a pull quote.

—Adam Michael Wood - Technical Content Writer

Line Blocks¶

Line blocks are useful for addresses, verse, and adornment-free lists. They are quoted by just a | pipe sign in front of each single line.

the example

1 2 3 4

| Each new line begins with a | vertical bar ("``|``"). | Line breaks and initial indents | are preserved.

which gives

Each new line begins with a

vertical bar (“|”).

Line breaks and initial indents

are preserved.

Doctest Blocks¶

Doctest blocks are interactive Python sessions cut-and-pasted into docstrings. They do not require the literal blocks syntax. The doctest block must end with a blank line and should not end with an unused prompt, see Doctest blocks in Sphinx for more informations.

the example

1 2 3 4 5 6 7 8 9 10 11 12

>>> print('this is a Doctest block') this is a Doctest block >>> print('Python-specific usage examples; begun with ">>>"') Python-specific usage examples; begun with ">>>" >>> print('(cut and pasted from interactive Python sessions)') (cut and pasted from interactive Python sessions) >>> a = [51,27,13,56] >>> b = dict(enumerate(a)) >>> print(b) {0: 51, 1: 27, 2: 13, 3: 56}

which gives

>>> print('this is a Doctest block')
this is a Doctest block

>>> print('Python-specific usage examples; begun with ">>>"')
Python-specific usage examples; begun with ">>>"
>>> print('(cut and pasted from interactive Python sessions)')
(cut and pasted from interactive Python sessions)

>>> a = [51,27,13,56]
>>> b = dict(enumerate(a))
>>> print(b)
{0: 51, 1: 27, 2: 13, 3: 56}

Unordered (bullet) Lists¶

Bullet lists contains list item elements which are uniformly marked with bullets. Bullets are typically simple dingbats (symbols) such as circles and squares.

bulleted lists ( <ul> )

the example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

* This is a bulleted list ... * ... use asterisks. * It has fife items, the third item uses two lines. * Are unindented at the first level. * Must have a blank line before and after. - This is a bulleted list ... - ... use hyphens. - Are indented at the first level to stand out from the previous paragraph. - the blank line requirement means that nested list items will have a blank line before and after as well - you may *optionally* put a blank line *between* list items

which gives

• This is a bulleted list …

• … use asterisks.

• It has fife items, the third item uses two lines.

• Are unindented at the first level.

• Must have a blank line before and after.

  • This is a bulleted list …

  • … use hyphens.

  • Are indented at the first level to stand out from the previous paragraph.

    • the blank line requirement means that nested list items will have a blank line before and after as well

    • you may optionally put a blank line between list items

Ordered (numbered) Lists¶

Enumerated lists (a.k.a. “ordered” lists) are similar to bullet lists, but use enumerators instead of bullets. An enumerator consists of an enumeration sequence member and formatting, followed by whitespace. Different enumeration sequences are possible, e.g. Arabic or Roman numerals or alphabet characters.

numbered lists ( <ol> )

the example

1 2 3 4 5 6 7 8 9 10 11

1. This is a numbered list. 2. Start each line with a number and period. 3. Can begin on any number. 8. Must have a blank line before and after. 9. Can have nested sub-lists. a. nested lists are numbered separately #. nested lists need a blank line before and after #. Can have automatic number with the ``#`` character.

which gives

1. This is a numbered list.

2. Start each line with a number and period.

3. Can begin on any number.

8. Must have a blank line before and after.

9. Can have nested sub-lists.

   1. nested lists are numbered separately

   2. nested lists need a blank line before and after

10. Can have automatic number with the # character.

Definition (description) Lists¶

Definition Lists contains a list of terms and their definitions. Each list item element contains a term, optional classifiers, and a definition.

definition list ( <dl> )

the example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

Definition list a list with several term-definition pairs in the form .. parsed-literal:: **TERM** DEFINITION (*description of term*) Terms should not be indented Definitions should be indented under the term Line spacing there should be a blank line between term-definition pairs

which gives

Definition list

a list with several term-definition pairs in the form

TERM
   DEFINITION (description of term)

Terms

should not be indented

Definitions

should be indented under the term

Line spacing

there should be a blank line between term-definition pairs

Comments¶

Every explicit markup block which is not a valid markup construct (like the footnotes above) is regarded as a comment.

However, it must have some text in the ".. " line, otherwise it is ignored, and content will be displayed (indented).

the example

1 2 3 4 5 6 7 8 9

.. This is a comment .. _so: is this! .. [and] this! .. this:: too! .. |even| this:: !

Directives¶

Directives are generic blocks of explicit markup. Besides Roles, it is one of the extension mechanisms of reStructuredText, and Sphinx makes heavy use of it. Basically, a directive consists of a name, arguments, options and content. Keep this terminology in mind, it is used in one of the next chapter describing custom directives.

the example

1 2 3 4 5

.. cpp:function:: char* foo(x) char* foo(y, z) :noindexentry: Return a line of text input from the user.

which gives

char *foo(x)¶

char *foo(y, z)¶

Return a line of text input from the user.

.. cpp:function:: is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option :noindexentry:. As you can see, options are given in the lines immediately following the arguments and indicated by the colons.

The directive content follows after a blank line and is indented relative to the directive start.

If you want to suppress the addition of an entry in the shown index, you can give the directive option flag :noindexentry:. If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :noindex: (which implies :noindexentry:).

Hint

As far as possible, all examples in this document use the :noindexentry: option to keep the automatically created index as clean as possible but still be able to reference it.

Footnotes¶

For footnotes, use [#]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading.

the example

1 2 3 4 5 6

Lorem ipsum [#]_ dolor sit amet ... [#]_ .. rubric:: Footnotes .. [#] Text of the first footnote. .. [#] Text of the second footnote.

which gives

Lorem ipsum 1 dolor sit amet … 2

Footnotes

1

Text of the first footnote.

2

Text of the second footnote.

You can also explicitly number the footnotes for better context.

Citations¶

Citations are identical to footnotes except that they use only non-numeric labels such as [note]_ or [GVR2001]_. Citation labels are simple reference names (case-insensitive single words consisting of alphanumerics plus internal hyphens, underscores, and periods; no whitespace). Citations may be rendered separately and differently from footnotes.

the example

1 2 3 4

Here is a citation reference: [CIT2002]_. .. [CIT2002] This is the citation. It's just like a footnote, except the label is textual.

which gives

Here is a citation reference: [CIT2002].

CIT2002

This is the citation. It’s just like a footnote, except the label is textual.

To use a professional bibliography, you should use the Sphinx extension BibTeX Citations.

SVG Graphics only¶

All vector graphics or diagrams should be SVG files. This helps us keep our graphic conversion tooling simple, and generally results in higher-quality representation. SVG graphics with an parameterized opacity (transparency) should be possible as well as an animated SVG, see Figure 1.1 and Figure 1.2.

Example of transparent SVG 1¶

Example of animated SVG 2¶

Whenever possible, you should generate your graphics as SVG rather than converting to SVG from another format. That avoids bitmap raster images embedded in a SVG container. The goal of SVG usage is to hold vector graphic as long as possible, from the editor up to the presentation. If you have to start in another vector graphic format use lossless vector formats whenever possible. These include EPS/PS, AI, DXF, EMF/EMZ, WMF/WMZ or some special XML vector graphics schemes. In any case avoid embedded bitmaps, as this is a lossy format for vector informations that does not replicate scaling very well. Figure 1.3 demonstrats differences between bitmapped raster and vector graphics. The bitmap raster is composed of a fixed set of pixels, while the vector is composed of a fixed set of shapes. In the picture, scaling the bitmap reveals the pixels while scaling the vector image preserves the shapes.

Demonstration of differences between bitmapped raster and vector images. 3¶

Bitmap raster images are good for photographic images or screenshots but not for stencils, sketches, diagrams or graphs and often they do not support transparency.

—Superuser - JPEG vs. PNG vs. BMP vs. GIF vs. SVG

Raster graphics are resolution dependent, meaning they cannot scale up to an arbitrary resolution without loss of apparent quality. This property contrasts with the capabilities of vector graphics, which easily scale up to the quality of the device rendering them. Raster graphics deal more practically than vector graphics with photographs and photo-realistic images, while vector graphics often serve better for typesetting or for graphic design.

—Wikipedia - Raster graphics

Vector graphics have the unique advantage over raster graphics in that the points, lines, and curves may be scaled up or down to any resolution with no aliasing.

—Wikipedia - Vector graphics

Footnotes

1

Indication of provenance: STEAMcoded.org: atom1.svg (public domain for teachers and students learning to code)

2

Indication of provenance: STEAMcoded.org: atom.svg (public domain for teachers and students learning to code)

3

Indication of provenance: Wikimedia: 6/6b/Bitmap_VS_SVG.svg (licensed under CC-BY-SA-2.5)

PNG Images only¶

All still bitmap raster images or photos should be PNG files. This helps us keep our image compression tooling simple, and generally results in higher-quality screenshots. PNG images with an 8-bit transparency channel should be possible as well as an animated PNG, see Figure 1.4 and Figure 1.5.

Example of transparent PNG 4¶

Example of animated PNG 5¶

Whenever possible, you should generate your images as PNG rather than converting to PNG from another format. If you have to start in another format, use lossless formats whenever possible. These include BMP/DIB, GIF, and TIFF. Avoid JPEG/JFIF if possible, as this is a lossy format that does not replicate screenshots very well. Figure 1.6 comparing lossy compression in JPEG with lossless compression in PNG: the JPEG artifacts can be easily visible in the background of this kind of image data, where the PNG image has solid color.

Demonstration of differences between lossy encoding and lossless method. 6¶

JPEG is good for photographic images but not for sharp transitions and does not support transparency.

—Wikipedia - PNG comparison with JPEG

The JPEG format can produce a smaller file than PNG for photographic (and photo-like) images, since JPEG uses a lossy encoding method specifically designed for photographic image data. Using PNG instead of a high-quality JPEG for such images would result in a large increase in filesize with negligible gain in quality. In comparison, when storing images that contain text, line art, or graphics – images with sharp transitions and large areas of solid color – the PNG format can compress image data more than JPEG can. Additionally, PNG is lossless, while JPEG produces visual artifacts around high-contrast areas.

JPEG’s lossy compression also suffers from generation loss, where repeatedly decoding and re-encoding an image to save it again causes a loss of information each time, degrading the image. This does not happen with repeated viewing or copying, but only if the file is edited and saved over again. Because PNG is lossless, it is suitable for storing images to be edited.

Where an image contains both sharp transitions and photographic parts, a choice must be made between the two effects:

Footnotes

4

Indication of provenance: Wikimedia: 4/47/PNG_transparency_demonstration_1.png (licensed under CC-BY-SA-3.0)

5

Indication of provenance: Wikimedia: 1/14/Animated_PNG_example_bouncing_beach_ball.png (released into the public domain by its author, Holger Will)

6

Indication of provenance: Superuser: a/55706, http://lbrandy.com/assets/jpg_vs_png2.png (licensed under CC-BY-SA-3.0)

Inserting¶

To place an graphic or image in a document, use the .. image:: directive (see Image).

.. image:: /img/{absolut-document-subdirectory}/{file}.svg
  :alt: Alt text. Every image should have descriptive alt text.

.. image:: {relative-document-subdirectory}/{file}.*
  :alt: Alt text. Every image should have descriptive alt text.

Note the literal asterisk (*) at the end, in place of a file extension. Use the asterisk, and omit the file extension (see reStructuredText Primer, section Images).

.. image::¶

The example

1 2 3 4 5 6 7 8 9

.. image:: /_images/lpn.svg :alt: The Li-Pro.Net logo. (explicitely as SVG) :height: 32px :width: 32px .. image:: /_images/lpn.* :alt: The Li-Pro.Net logo. (scaled to the half) :scale: 50 % :align: right

Which gives

Inserting with Captions¶

Use .. figure:: directive to markup a graphic or image with a caption (see Figure).

.. figure:: {file-with-directory-same-as-for image}.*
  :alt: Alt text. Every image should have descriptive alt text.

  The rest of the indented content will be the (optional) caption.
  This can be a short sentence or multiline paragraph.

Captions can contain any other complex reStructuredText markup. Further paragraphs after the caption will be the (optional) legend which are also arbitrary body elements.

.. figure::¶

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

.. figure:: /_images/lpn.* :name: the-lpn-logo :alt: The Li-Pro.Net logo. :figclass: align-center :align: center :scale: 75 % The |ghlpn|_ logo. Legend of all elements you can see in the graphic: .. list-table:: The legend for the |ghlpn|_ logo. :widths: 10 40 :width: 50 % :align: center :header-rows: 1 :stub-columns: 1 * - Letter - Meaning * - L (in blue) - Li * - P (in blue) - Pro * - N (in red) - Net .. |ghlpn| unicode:: Li U+02013 Pro.Net U+0040 GitHub .. _`ghlpn`: https://github.com/lipro

Which gives

The Li–Pro.Net@GitHub logo.¶

Legend of all elements you can see in the graphic:

The legend for the Li–Pro.Net@GitHub logo.¶

Letter	Meaning
L (in blue)	Li
P (in blue)	Pro
N (in red)	Net

Inserting Inline¶

To information on creating inline images, see Inline Image.

Grid Style¶

For more details, see Grid Tables in Docutils.

the example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth} .. table:: Example table in grid style :name: tables-grid-example :widths: 20, 30, 50 :class: longtable :align: center :width: 66% +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+

which gives

Example table in grid style¶

Header 1	Header 2	Header 3
body row 1	column 2	column 3
body row 2	Cells may span columns.
body row 3	Cells may span rows.	Cells contain blocks.
body row 4

Simple Style¶

For more details, see Simple Tables in Docutils.

the example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth} .. table:: Example table in simple style :name: tables-simple-example :widths: 20, 30, 50 :align: center :width: 66% ====== ====== ====== Inputs Output ------------- ------ A B A or B ====== ====== ====== False -------------------- True -------------------- True False True ------ ------ ------ False True ====== =============

which gives

Example table in simple style¶

Inputs		Output
A	B	A or B
False
True
True	False	True
False	True

List Table¶

.. list-table::¶

For more details, see List Tables in Docutils.

Hint

For table content that needs a higher complexity than the list table is able to support use the flat-table.

The example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth} .. list-table:: Example list table :name: tables-list-example :widths: 20, 30, 50 :class: longtable :header-rows: 1 :align: center :width: 66% * - Treat - Quantity - Description * - Albatross - 2.99 - On a stick! * - Crunchy Frog - 1.49 - If we took the bones out, it would not be crunchy, now would it? * - Gannet Ripple - 1.99 - On a stick!

Which gives

Example list table¶

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it would not be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

CSV Table¶

.. csv-table::¶

For more details, see CSV Tables in Docutils.

Hint

In almost all cases, csv-table is the easiest and most maintainable way to insert a table into a document. It should be preferred unless there is a compelling reason to use one of the other styles.

The example

1 2 3 4 5 6 7 8 9 10 11 12 13

.. tabularcolumns:: p{0.132\linewidth}p{0.198\linewidth}p{0.330\linewidth} .. csv-table:: Example CSV table :name: tables-csv-example :header: "Treat", "Quantity", "Description" :widths: 20, 30, 50 :class: longtable :align: center :width: 66% "Albatross", 2.99, "On a stick!" "Crunchy Frog", 1.49, "If we took the bones out, it would not be crunchy, now would it?" "Gannet Ripple", 1.99, "On a stick!"

Which gives

Example CSV table¶

Treat	Quantity	Description
Albatross	2.99	On a stick!
Crunchy Frog	1.49	If we took the bones out, it would not be crunchy, now would it?
Gannet Ripple	1.99	On a stick!

Some of the options recognized are:

:widths:¶

Contains a comma or space-separated list of relative column widths. The default is equal-width columns.

The special value auto may be used by writers to decide whether to delegate the determination of column widths to the backend.

In most cases, the best result is either the default or auto. If you’re unsure, try it both ways and see which looks better to you.

:header:¶

Contains column titles. It must use the same CSV format as the main CSV data.

:delim:¶

Contains a one character string used to separate fields. Default value is comma. It must be a single character or Unicode code.

The only reason to use something other than a comma is when copying large blocks of content from another source that uses a different style. If you are creating new table content yourself, use the comma.

The example

1 2 3 4 5 6 7 8 9 10

.. csv-table:: Example CSV table with customized delimiter :name: tables-csv-delim-example :header: "Name", "Password" :widths: auto :delim: : :align: center :width: 66% "Peter":":literal:`QW8rTn@*emk;=J3f`" "Paul":":literal:`b3%C/-9\`][cnG,;{`"

Which gives

Example CSV table with customized delimiter¶

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

:align:¶

It specifies the horizontal alignment of the table. It can be left, right or center.

The example

1 2 3 4 5 6 7 8

.. csv-table:: Example CSV table with right alignment :name: tables-csv-align-example :header: "Name", "Password" :delim: # :align: right "Peter"#":literal:`QW8rTn@*emk;=J3f`" "Paul"# ":literal:`b3%C/-9\`][cnG,;{`"

Which gives

Example CSV table with right alignment¶

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

:url:¶

Contains an Internet URL reference to a CSV data file.

:file:¶

Contains the local file system path to a CSV data file.

The example

1 2 3 4 5 6 7 8

.. csv-table:: Example CSV table from source file :name: tables-csv-srcfile-example :file: example.csv :delim: | :encoding: utf-8-sig :header-rows: 1 :stub-columns: 1 :width: 66%

Which gives

Example CSV table from source file¶

Name	Password
Peter	QW8rTn@*emk;=J3f
Paul	b3%C/-9`][cnG,;{

Which needs

The example above processed the following CSV file content:

CSV example file (tables/csv/srcfile/example.csv)¶

1 2 3

Name|Password Peter|:literal:`QW8rTn@*emk;=J3f` Paul|:literal:`b3%C/-9\`][cnG,;{`

Note

There is no support for checking that the number of columns in each row is the same. However, this directive supports CSV generators that do not insert “empty” entries at the end of short rows, by automatically adding empty entries.

Explicit Code Blocks¶

Source code will be formatted by the directive .. code-block::. Sphinx, like Python, uses meaningful whitespace. Blocks of content are structured based on the indention level they are on.

.. code-block::¶

For more details, see code-block directive.

The example

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

.. highlight:: bash :linenothreshold: 1 A cool bit of code:: #!/bin/bash # Some cool Bash code echo ${BASH_VERSINFO[*]} .. highlight:: none .. code-block:: rst :caption: Documentation A bit of **rst** which should be *highlighted* properly. .. code-block:: python :caption: Script :linenos: import sys sys.exit(1)

Which gives

A cool bit of code:

1 2 3

#!/bin/bash # Some cool Bash code echo ${BASH_VERSINFO[*]}

Documentation¶

A bit of **rst** which should be *highlighted* properly.

Script¶

1 2	import sys sys.exit(1)

Valid values for the highlighting :language: (first argument) are:

• none (no highlighting)

• python (the default)

• c and cpp (C/C++)

• rst or rest (reStructuredText)

• bash or ksh or sh (Unix Shell scripts)

• shell-session (Unix Shell sessions)

• ps1 or posh or powershell (Windows PowerShell code)

• ps1con (Windows PowerShell sessions)

• dosbatch or winbatch (MS-DOS/Windows Batch file)

• doscon (MS-DOS sessions)

• cfg or ini (Generic configuration file, mostly INI files)

• sql (Generic SQL commands)

• registry (Windows Registry files produced by regedit)

• guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)

• … and any other lexer alias that Pygments supports.

Explicit Code Includes¶

If the text resides in a separate file, use the .. literalinclude:: directive:

.. literalinclude::¶

For more details, see literalinclude directive.

The example

1 2	.. literalinclude:: /docutils.conf :language: cfg

Which gives

;
; Docutils Configuration
;
; The configuration file consists of sections, lead by a "[section]"
; header and followed by "name: value" entries, with continuations
; in the style of RFC 822; "name=value" is also accepted. Note that
; leading whitespace is removed from values. ... Lines beginning
; with "#" or ";" are ignored and may be used to provide comments.
;
; see: https://docutils.sourceforge.io/docs/user/config.html
;

; https://docutils.sourceforge.io/docs/user/config.html#parsers
; https://docutils.sourceforge.io/docs/user/config.html#restructuredtext-parser

[restructuredtext parser]
syntax_highlight = short

All included files could be located under /include. The beginning / means, root directory of the documentation source directory. Without it, the path is relative to the directory of the including file.

Generic Admonition¶

The Generic admonition is a simple titled admonition. The title may be anything the author desires. The author-supplied title is also used as a “classes” attribute value after being converted into a valid identifier form. As well as this implicitly behavior the :class: option value can set to any implemented specific type and overrides the computed “classes” attribute value.

.. admonition::¶

The example

1 2 3 4 5 6

.. admonition:: Neque porro quisquam :class: error Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus mattis commodo eros, quis posuere enim lobortis quis. Nullam ut tempus nibh.

Which gives

Neque porro quisquam

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus mattis commodo eros, quis posuere enim lobortis quis. Nullam ut tempus nibh.

Specific Admonitions¶

Specific Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. The following admonition directives have been implemented.

Sphinx Additional Admonitions¶

Other Semantic Markup¶

:abbr:¶

Marks up an abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML. For more details, see abbr role.

The example

1 2	This is the :abbr:`ISDN (Integrated Services Digital Network)` device.

Which gives

This is the ISDN device.

:dfn:¶

Marks the defining instance of a term outside the index or glossary. For more details, see dfn role.

The example

1 2	This library has a :dfn:`CAPI`, a Common ISDN Application Programming Interface.

Which gives

This library has a CAPI, a Common ISDN Application Programming Interface.

Create a Glossary¶

.. glossary::¶

For more details, see glossary directive.

To add glossary terms, you use the directive .. glossary::. Write each glossary entry as a definition list, with a term, followed by a single-line indented definition.

Each glossary entry is nested below the .. glossary:: directive. For example:

.. glossary::

    Sphinx
       Sphinx is a tool that makes it easy to create intelligent and
       beautiful documentation. It was originally created for the
       Python documentation, and it has excellent facilities for the
       documentation of software projects in a range of languages.

    RST
       reStructuredText is an easy-to-read, what-you-see-is-what-you-get
       plain text markup syntax and parser system. It is useful for
       in-line program documentation (such as Python docstrings), for
       quickly creating simple web pages, and for standalone documents.
       reStructuredText is designed for extensibility for specific
       application domains. The reStructuredText parser is a component
       of Docutils.

    Sublime Text
       Sublime Text is a sophisticated text editor for code, markup
       and prose. You'll love the slick user interface, extraordinary
       features and amazing performance.

Link a Term to its Glossary Entry¶

:term:¶

For more details, see index role.

When a glossary term is used in text, you can link it to its definition with the :term: role. For example, to link the term Sphinx to its definition, use the following syntax:

:term:`Sphinx`

The term specified must exactly match a term in Glossary directive.

You can link to a term in the glossary while showing different text in the topic by including the term in angle brackets. For example:

:term:`reStructuredText<RST>`

The term in angle brackets must exactly match a term in the glossary. The text before the angle brackets is what users see on the page.

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.

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

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.

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

:which gives:

   .. include:: matplotlib/mplot3d/example.rsti