Chapter Title

Here is more Restructuredtext and Sphinx directives.

Section title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec.

Subsection title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec.


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec.

Paragrap title

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec lorem neque, interdum in ipsum nec.

No matter where you go, there you are.

—Buckaroo Banzai

This is an example of text ®. This text is in italics and this is some other in bold, if we wanto to put some inline code we put it like that and finally there is some superscript things and some subscript things. If we reference a book title we can show it like this: Book Title. Some autosubstitutions are the release and today date like this: 1.0.0 and Apr 05, 2023.

This is centered text!

“Quote Paragraph”
Pull Quote text
Highlights Quote text
Custom Container class.

more info Read more about the Table of Contents with a substitution for the image and a link made by a toctree name reference.

This word Sphinx with its definition needs to be in the glossary or it will rise an error.

This paragraph might be rendered in a custom way.

See PEP 287 for more information about reStructuredText. And also a RFC 2822 reference for more info about the RFC references.

Modify HTML metadata like description and keywords here.

Original Text directives were Emphasis. Strong. Literal. Subscript. Superscript. Title-Reference

Area of a circle is \(A_\text{c} = (\pi/4) d^2\).

\begin{eqnarray} y & = & ax^2 + bx + c \\ f(x) & = & x^2 + 2xy + y^2 \end{eqnarray}
(1)\[e^{i\pi} + 1 = 0\]

Euler’s identity, equation (1), was elected one of the most beautiful mathematical formulas.

Topic Title

Subsequent indented lines comprise the body of the topic.

New in version 2.5: For the change log features added to the program.

Changed in version 1.4: For the change log features changed to the program.

Deprecated since version 2.5.9: For the change log features deprecated to the program.

Paragraph 1

Literal Block.

Paragraph 2

Paragraph 1, Literal Block and Paragraph 2 are semantically one compound paragraph.

  1. Arabic numerals.
    1. lower alpha
      1. upper alpha.
  • A bullet list

    • Nested bullet list.

    • Nested item 2.

      Paragrap 2 of item 2

  • A list of
  • short items
  • that should be
  • displayed
  • horizontally

Section Heading Reference

Paragraph with links, can be standalone hyperlinks ( , external links Google_ or some internal cross-reference (sectionTitleRef) or with custom text like Custom Title Text, external links with custom text like Google Link. Custom text using an external link for the URL is like Google Link 2 <Google_>_. We can also use internally the ref directive :ref:`sectionTitleRef.

For footnotes and citations they can be manual [1] , auto-numbered without label [3] , with label [2] , or with symbols [*] . For citations they can be also manual [11] or with text [cit1]. We can replace any text with replace directive like THIS..

We can use section headers as targets like Section Heading Reference. We can also use inline text targets like can be standalone hyperlinks. An uncommon way of targeting is with anonymous links like any random text [4].

Link to autodocs class Foo: test.Foo.

Here are some auto target footnotes:




A numbered footnote.

With a second indented paragraph.


A autofootnote using a name.

Can be referenced using a normal reference or a hyperlink reference.

[3]An anonymous autofootnote.
[*]A symbol footnote.
[†]Next symbol footnote etc.
[11]This is the citation I made, let’s make this extremely long so that we can tell that it doesn’t follow the normal responsive table stuff.
[cit1](1, 2) This citation has some meta citation to [13] too.
[13]This citation is referenced in the previews citation.

Here’s the second reference to the above, [cit1].


They are written like:


They represent any object in the docs, some create links.

  • any (test) searches with doc, ref, option, extension and intersphinx
  • ref (Section Heading Reference) use with headers, tables and figures.
  • doc (test) is used to reference a document.
    • :doc:`test` in a/b/index is a/b/test.
    • :doc:`/test` in a/b/index is a/test.
  • download (image) indicates a document is to be downloaded.
  • numref (Chart of Figure Caption (Fig. 1)) numbered figure, table or block code.
    • numfig=True must be set. Optionally numfig-format and numfig_secnum_depth.
  • envvar (PATH) enviroment variable set with an envvar directive.
  • token (examplegrammar) references a token in a productionlist.
  • option (secondexecutable -t) references an option of a command directive.
  • term (Sphinx) references a term in the glossary.
  • math (\((\pi/4) d^2\)) creates inline math.
  • eq ((1)) its the same as math:numref and references a math directive label.
  • menuselection (Home ‣ File ‣ Some menu) menu selection sequence.
  • guilabel (User action) references a user action, or a part of the interface,
  • file (/usr/lib/pythonx/some) is a reference to a file or directory.
  • abbr (LIFO) makes a tooltip for an abbreviation.
  • samp (print 1+var) is a reference to inline code with a custom variable.
  • mimetype (text/html) is a reference to a MIME Type file.
  • manpage (man.1) references Unix Manual Page. Manpages_url must be defined.
  • regexp (2(x|*|-)4) is a reference to a regex expresion but just in literal.
  • dfn (important-word) a term that holds the main idea of a paragraph.
  • kbd (Control-x Control-f) keyboard key combination that the user must press.
  • mailheader (Message/Partial) is a reference to a RFC822_ Mail header.
  • newsgroup (comp.programming) is a reference to a Usenet newsgroup.
  • command (mkdir) is a reference to an OS level command like mkdir.
  • makevar (SOMEVAR) is a reference to a variable for a makefile.
  • program (firstexecutable) is a reference to an executable program.
  • index (name) is a reference to an index entry.
examplegrammar ::=  "try" ":" suite
-t testArg <optionalTestArg>, --test testArg

Test Option One Description.

-t testArg <optionaltestArg>

Test Option Two Description.

Term, Options and Fields

To insert a termin definition we indent the definition:

Term definition.

This is an command options list:

-a command-line option “a”
-b file options can have arguments and long descriptions
--long options can be long also
--input=file long options can also have arguments
-x, -y, -z Multiple options are an “option group”.
-v, --verbose Commonly-seen: short & long options.
-1 file, --one=file, --two file
 Multiple options with arguments.

To insert a field list, we can define any role we desire like author, address, contact, authors, organization, date, status, revision, version, copyright, dedication and abstract:

Author:David Goodger
Dedication:For Docutils users & co-developers.
abstract:This document is a demonstration of the reStructuredText markup language, containing examples of all basic reStructuredText constructs and many advanced constructs.

Images and Tables

Complex Table:

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

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

Table with a title:

Table 1 Truth table for “not”
A not A
False True
True False

CSV Table:

Table 2 Frozen Delights!
Treat Quantity Description
Albatross 2.99 On a stick!
Crunchy Frog 1.49 If we took the bones out, it wouldn’t be crunchy
Gannet Ripple 1.99 On a stick!

List Table:

Table 3 List tables can have captions like this one.
List table Header 1 Header 2 Header 3 long. Lorem ipsum dolor sit amet
Stub Row 1 Row 1 Column 2 Column 3 long. Lorem ipsum dolor sit amet
Stub Row 2 Row 2 Column 2 Column 3 long. Lorem ipsum dolor sit amet
Stub Row 3 Row 3 Column 2 Column 3 long. Lorem ipsum dolor sit amet


Image Alternative Description

Fig. 1 Figure Caption

It can also have a figure leyend with anything else.

Code Blocks

First Auto Code:

First Code Block

Second Auto Code

Second Code Block

Sphinx Code Block:

Listing 1 Code Blocks can have captions.
.. toctree::
   :caption: Table of Contents
   :name: mastertoc
   :maxdepth: 2

   Custom TocTree Title <intro>

Sphinx Code Block Custom Start:

First code starts at 10
The next code line

Sphinx Simple Code:

Some bash code
echo 'hello world'

Sphinx Code Block With a name:

Listing 2
 First code line of referenced block.
 The next code line
 This block is also not indented.

Then you can reference this This Code Block code block.

Sphinx File Code:

templates_path = ['_templates']

Doctest Block:

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



Some text for the WARNING.


Some text for the ATTENTION.


Some text for the CAUTION.


Some text for the DANGER


Some text for the ERROR.


Some text for the HINT.


Some text for the IMPORTANT.


Some text for the TIP.


Some text for the NOTE.

See also

Module zipfile
For docs on that standard module.
Other docs link
This is the docs of the RTD theme.

And, by the way…

You can make up your own admonition too.