'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SPHINX-ALL" "1" "May 01, 2024" "7.3.7" "Sphinx"
.SH NAME
sphinx-all \- Sphinx documentation generator system manual
.INDENT 0.0
.INDENT 3.5
Sphinx makes it easy to create intelligent and beautiful documentation.
.UNINDENT
.UNINDENT
.sp
Here are some of Sphinx\(aqs major features:
.INDENT 0.0
.IP \(bu 2
\fBOutput formats:\fP HTML (including Windows HTML Help), LaTeX (for printable
PDF versions), ePub, Texinfo, manual pages, plain text
.IP \(bu 2
\fBExtensive cross\-references:\fP semantic markup and automatic links for
functions, classes, citations, glossary terms and similar pieces of
information
.IP \(bu 2
\fBHierarchical structure:\fP easy definition of a document tree, with automatic
links to siblings, parents and children
.IP \(bu 2
\fBAutomatic indices:\fP general index as well as a language\-specific module
indices
.IP \(bu 2
\fBCode handling:\fP automatic highlighting using the \X'tty: link https://pygments.org/'\fI\%Pygments\fP\X'tty: link' highlighter
.IP \(bu 2
\fBExtensions:\fP automatic testing of code snippets, inclusion of docstrings
from Python modules (API docs) via \X'tty: link #builtin-extensions'\fI\%built\-in extensions\fP\X'tty: link', and much more functionality via \X'tty: link #third-party-extensions'\fI\%third\-party
extensions\fP\X'tty: link'\&.
.IP \(bu 2
\fBThemes:\fP modify the look and feel of outputs via \fI\%creating themes\fP, and reuse many \X'tty: link #third-party-themes'\fI\%third\-party themes\fP\X'tty: link'\&.
.IP \(bu 2
\fBContributed extensions:\fP dozens of extensions \X'tty: link #third-party-extensions'\fI\%contributed by users\fP\X'tty: link'; most of them installable from PyPI.
.UNINDENT
.sp
Sphinx uses the \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText\fP\X'tty: link' markup language by default, and can read
\X'tty: link #markdown'\fI\%MyST markdown\fP\X'tty: link' via third\-party extensions. Both of these
are powerful and straightforward to use, and have functionality
for complex documentation and publishing workflows. They both build upon
\X'tty: link https://docutils.sourceforge.io/'\fI\%Docutils\fP\X'tty: link' to parse and write documents.
.sp
See below for how to navigate Sphinx\(aqs documentation.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
The \X'tty: link contents.html'\fI\%Sphinx documentation Table of Contents\fP\X'tty: link' has
a full list of this site\(aqs pages.
.UNINDENT
.UNINDENT
.SH GET STARTED
.sp
These sections cover the basics of getting started with Sphinx, including
creating and building your own documentation from scratch.
.SS Getting Started
.sp
Sphinx is a \fIdocumentation generator\fP or a tool that translates a set of plain
text source files into various output formats, automatically producing
cross\-references, indices, etc. That is, if you have a directory containing a
bunch of \fI\%reStructuredText\fP or \fI\%Markdown\fP
documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
man pages and much more.
.sp
Sphinx focuses on documentation, in particular handwritten documentation,
however, Sphinx can also be used to generate blogs, homepages and even books.
Much of Sphinx\(aqs power comes from the richness of its default plain\-text markup
format, \fI\%reStructuredText\fP, along with
its \fI\%significant extensibility capabilities\fP\&.
.sp
The goal of this document is to give you a quick taste of what Sphinx is and
how you might use it. When you\(aqre done here, you can check out the
\fI\%installation guide\fP followed by the intro to the
default markup format used by Sphinx, \fI\%reStructuredText\fP\&.
.sp
For a great \(dqintroduction\(dq to writing docs in general \-\- the whys and hows, see
also \X'tty: link https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/'\fI\%Write the docs\fP\X'tty: link', written by Eric Holscher.
.SS Setting up the documentation sources
.sp
The root directory of a Sphinx collection of plain\-text document sources is
called the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link'\&. This directory also contains the Sphinx
configuration file \fBconf.py\fP, where you can configure all aspects of how
Sphinx reads your sources and builds your documentation. [1]
.sp
Sphinx comes with a script called \fBsphinx\-quickstart\fP that sets up a
source directory and creates a default \fBconf.py\fP with the most useful
configuration values from a few questions it asks you. To use this, run:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ sphinx\-quickstart
.EE
.UNINDENT
.UNINDENT
.SS Defining document structure
.sp
Let\(aqs assume you\(aqve run \fBsphinx\-quickstart\fP\&. It created a source
directory with \fBconf.py\fP and a root document, \fBindex.rst\fP\&. The
main function of the \X'tty: link #term-root-document'\fI\%root document\fP\X'tty: link' is to serve as a welcome page, and
to contain the root of the \(dqtable of contents tree\(dq (or \fItoctree\fP). This is one
of the main things that Sphinx adds to reStructuredText, a way to connect
multiple files to a single hierarchy of documents.
.SS reStructuredText directives
.sp
\fBtoctree\fP is a reStructuredText \fIdirective\fP, a very versatile piece
of markup. Directives can have arguments, options and content.
.sp
\fIArguments\fP are given directly after the double colon following the
directive\(aqs name. Each directive decides whether it can have arguments, and
how many.
.sp
\fIOptions\fP are given after the arguments, in form of a \(dqfield list\(dq. The
\fBmaxdepth\fP is such an option for the \fBtoctree\fP directive.
.sp
\fIContent\fP follows the options or arguments after a blank line. Each
directive decides whether to allow content, and what to do with it.
.sp
A common gotcha with directives is that \fBthe first line of the content must
be indented to the same level as the options are\fP\&.
.sp
The \fBtoctree\fP directive initially is empty, and looks like so:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:maxdepth: 2
.EE
.UNINDENT
.UNINDENT
.sp
You add documents listing them in the \fIcontent\fP of the directive:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
.EE
.UNINDENT
.UNINDENT
.sp
This is exactly how the \fBtoctree\fP for this documentation looks. The
documents to include are given as \X'tty: link #term-document-name'\fI\%document name\fP\X'tty: link's, which in short
means that you leave off the file name extension and use forward slashes
(\fB/\fP) as directory separators.
.sp
[image: more info]
[image]
Read more about \X'tty: link #toctree-directive'\fI\%the toctree directive\fP\X'tty: link'\&.
.sp
You can now create the files you listed in the \fBtoctree\fP and add content, and
their section titles will be inserted (up to the \fBmaxdepth\fP level) at the
place where the \fBtoctree\fP directive is placed. Also, Sphinx now knows about
the order and hierarchy of your documents. (They may contain \fBtoctree\fP
directives themselves, which means you can create deeply nested hierarchies if
necessary.)
.SS Adding content
.sp
In Sphinx source files, you can use most features of standard
\X'tty: link #term-reStructuredText'\fI\%reStructuredText\fP\X'tty: link'\&. There are also several features added by Sphinx.
For example, you can add cross\-file references in a portable way (which works
for all output types) using the \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role.
.sp
For an example, if you are viewing the HTML version, you can look at the source
for this document \-\- use the \(dqShow Source\(dq link in the sidebar.
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Update the below link when we add new guides on these.
.UNINDENT
.UNINDENT
.sp
[image: more info]
[image]
See \fI\%reStructuredText\fP for a more in\-depth
introduction to reStructuredText, including markup added by Sphinx.
.SS Running the build
.sp
Now that you have added some files and content, let\(aqs make a first build of the
docs. A build is started with the \fBsphinx\-build\fP program:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ sphinx\-build \-M html sourcedir outputdir
.EE
.UNINDENT
.UNINDENT
.sp
where \fIsourcedir\fP is the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link', and \fIoutputdir\fP is the
directory in which you want to place the built documentation.
The \X'tty: link #cmdoption-sphinx-build-M'\fI\%\-M\fP\X'tty: link' option selects a builder; in this example
Sphinx will build HTML files.
.sp
[image: more info]
[image]
Refer to the \fI\%sphinx\-build man page\fP for all
options that \fBsphinx\-build\fP supports.
.sp
However, \fBsphinx\-quickstart\fP script creates a \fBMakefile\fP and a
\fBmake.bat\fP which make life even easier for you. These can be executed by
running \fBmake\fP with the name of the builder. For example.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ make html
.EE
.UNINDENT
.UNINDENT
.sp
This will build HTML docs in the build directory you chose. Execute
\fBmake\fP without an argument to see which targets are available.
.INDENT 0.0
.INDENT 3.5
.IP "How do I generate PDF documents?"
.sp
\fBmake latexpdf\fP runs the \X'tty: link #sphinx.builders.latex.LaTeXBuilder'\fI\%LaTeX builder\fP\X'tty: link' and readily invokes the pdfTeX
toolchain for you.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Move this whole section into a guide on rST or directives
.UNINDENT
.UNINDENT
.SS Documenting objects
.sp
One of Sphinx\(aqs main objectives is easy documentation of \fIobjects\fP (in a
very general sense) in any \fIdomain\fP\&. A domain is a collection of object
types that belong together, complete with markup to create and reference
descriptions of these objects.
.sp
The most prominent domain is the Python domain. For example, to document
Python\(aqs built\-in function \fBenumerate()\fP, you would add this to one of your
source files.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
.EE
.UNINDENT
.UNINDENT
.sp
This is rendered like this:
.INDENT 0.0
.TP
.B enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
\fIsequence\fP\&. (And so on.)
.UNINDENT
.sp
The argument of the directive is the \fIsignature\fP of the object you
describe, the content is the documentation for it. Multiple signatures can be
given, each in its own line.
.sp
The Python domain also happens to be the default domain, so you don\(aqt need to
prefix the markup with the domain name.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. function:: enumerate(sequence[, start=0])
...
.EE
.UNINDENT
.UNINDENT
.sp
does the same job if you keep the default setting for the default domain.
.sp
There are several more directives for documenting other types of Python
objects, for example \X'tty: link #directive-py-class'\fI\%py:class\fP\X'tty: link' or \X'tty: link #directive-py-method'\fI\%py:method\fP\X'tty: link'\&. There is
also a cross\-referencing \fIrole\fP for each of these object types. This
markup will create a link to the documentation of \fBenumerate()\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
The :py:func:\(gaenumerate\(ga function can be used for ...
.EE
.UNINDENT
.UNINDENT
.sp
And here is the proof: A link to \fI\%enumerate()\fP\&.
.sp
Again, the \fBpy:\fP can be left out if the Python domain is the default one. It
doesn\(aqt matter which file contains the actual documentation for
\fBenumerate()\fP; Sphinx will find it and create a link to it.
.sp
Each domain will have special rules for how the signatures can look like, and
make the formatted output look pretty, or add specific features like links to
parameter types, e.g. in the C/C++ domains.
.sp
[image: more info]
[image]
See \fI\%Domains\fP for all the available domains
and their directives/roles.
.SS Basic configuration
.sp
Earlier we mentioned that the \fBconf.py\fP file controls how Sphinx
processes your documents. In that file, which is executed as a Python source
file, you assign configuration values. For advanced users: since it is
executed by Sphinx, you can do non\-trivial tasks in it, like extending
\X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' or importing a module to find out the version you are
documenting.
.sp
The config values that you probably want to change are already put into the
\fBconf.py\fP by \fBsphinx\-quickstart\fP and initially commented out
(with standard Python syntax: a \fB#\fP comments the rest of the line). To
change the default value, remove the hash sign and modify the value. To
customize a config value that is not automatically added by
\fBsphinx\-quickstart\fP, just add an additional assignment.
.sp
Keep in mind that the file uses Python syntax for strings, numbers, lists and
so on. The file is saved in UTF\-8 by default, as indicated by the encoding
declaration in the first line.
.sp
[image: more info]
[image]
See \fI\%Configuration\fP for documentation of all available
config values.
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Move this entire doc to a different section
.UNINDENT
.UNINDENT
.SS Autodoc
.sp
When documenting Python code, it is common to put a lot of documentation in the
source files, in documentation strings. Sphinx supports the inclusion of
docstrings from your modules with an \fIextension\fP (an extension is a Python
module that provides additional features for Sphinx projects) called \fIautodoc\fP\&.
.sp
In order to use \fIautodoc\fP, you need to activate it in \fBconf.py\fP by
putting the string \fB\(aqsphinx.ext.autodoc\(aq\fP into the list assigned to the
\X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link' config value:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
extensions = [\(aqsphinx.ext.autodoc\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
Then, you have a few additional directives at your disposal. For example, to
document the function \fBio.open()\fP, reading its signature and
docstring from the source file, you\(aqd write this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. autofunction:: io.open
.EE
.UNINDENT
.UNINDENT
.sp
You can also document whole classes or even modules automatically, using member
options for the auto directives, like
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. automodule:: io
:members:
.EE
.UNINDENT
.UNINDENT
.sp
\fIautodoc\fP needs to import your modules in order to extract the docstrings.
Therefore, you must add the appropriate path to \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' in your
\fBconf.py\fP\&.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
\X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link' \fBimports\fP the modules to be documented. If any
modules have side effects on import, these will be executed by \fBautodoc\fP
when \fBsphinx\-build\fP is run.
.sp
If you document scripts (as opposed to library modules), make sure their
main routine is protected by a \fBif __name__ == \(aq__main__\(aq\fP condition.
.UNINDENT
.UNINDENT
.sp
[image: more info]
[image]
See \X'tty: link #module-sphinx.ext.autodoc'\fI\%sphinx.ext.autodoc\fP\X'tty: link' for the complete description of the
features of autodoc.
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Move this doc to another section
.UNINDENT
.UNINDENT
.SS Intersphinx
.sp
Many Sphinx documents including the \X'tty: link https://docs.python.org/3'\fI\%Python documentation\fP\X'tty: link' are published on
the Internet. When you want to make links to such documents from your
documentation, you can do it with \X'tty: link #module-sphinx.ext.intersphinx'\fI\%sphinx.ext.intersphinx\fP\X'tty: link'\&.
.sp
In order to use intersphinx, you need to activate it in \fBconf.py\fP by
putting the string \fB\(aqsphinx.ext.intersphinx\(aq\fP into the \X'tty: link #confval-extensions'\fI\%extensions\fP\X'tty: link'
list and set up the \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' config value.
.sp
For example, to link to \fBio.open()\fP in the Python library manual, you need to
setup your \X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
intersphinx_mapping = {\(aqpython\(aq: (\(aqhttps://docs.python.org/3\(aq, None)}
.EE
.UNINDENT
.UNINDENT
.sp
And now, you can write a cross\-reference like \fB:py:func:\(gaio.open\(ga\fP\&. Any
cross\-reference that has no matching target in the current documentation set,
will be looked up in the documentation sets configured in
\X'tty: link #confval-intersphinx_mapping'\fI\%intersphinx_mapping\fP\X'tty: link' (this needs access to the URL in order to
download the list of valid targets). Intersphinx also works for some other
\X'tty: link #term-domain'\fI\%domain\fP\X'tty: link'\(aqs roles including \fB:ref:\fP, however it doesn\(aqt work for
\fB:doc:\fP as that is non\-domain role.
.sp
[image: more info]
[image]
See \X'tty: link #module-sphinx.ext.intersphinx'\fI\%sphinx.ext.intersphinx\fP\X'tty: link' for the complete description of the
features of intersphinx.
.SS More topics to be covered
.INDENT 0.0
.IP \(bu 2
\fI\%Other extensions\fP:
.IP \(bu 2
Static files
.IP \(bu 2
\fI\%Selecting a theme\fP
.IP \(bu 2
\X'tty: link #templating'\fI\%Templating\fP\X'tty: link'
.IP \(bu 2
Using extensions
.IP \(bu 2
\X'tty: link #dev-extensions'\fI\%Writing extensions\fP\X'tty: link'
.UNINDENT
.SH FOOTNOTES
.IP [1] 5
This is the usual layout. However, \fBconf.py\fP can also live in
another directory, the \X'tty: link #term-configuration-directory'\fI\%configuration directory\fP\X'tty: link'\&. Refer to the
\fI\%sphinx\-build man page\fP for more information.
.SS Installing Sphinx
.INDENT 0.0
.IP \(bu 2
\fI\%Overview\fP
.IP \(bu 2
\fI\%Linux\fP
.IP \(bu 2
\fI\%macOS\fP
.IP \(bu 2
\fI\%Windows\fP
.IP \(bu 2
\fI\%Installation from PyPI\fP
.IP \(bu 2
\fI\%Docker\fP
.IP \(bu 2
\fI\%Installation from source\fP
.UNINDENT
.SS Overview
.sp
Sphinx is written in \X'tty: link https://docs.python-guide.org/'\fI\%Python\fP\X'tty: link' and supports Python 3.9+. It builds upon the
shoulders of many third\-party libraries such as \X'tty: link https://docutils.sourceforge.io/'\fI\%Docutils\fP\X'tty: link' and \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja\fP\X'tty: link',
which are installed when Sphinx is installed.
.SS Linux
.SS Debian/Ubuntu
.sp
Install either \fBpython3\-sphinx\fP using \fBapt\-get\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ apt\-get install python3\-sphinx
.EE
.UNINDENT
.UNINDENT
.sp
If it not already present, this will install Python for you.
.SS RHEL, CentOS
.sp
Install \fBpython\-sphinx\fP using \fByum\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ yum install python\-sphinx
.EE
.UNINDENT
.UNINDENT
.sp
If it not already present, this will install Python for you.
.SS Other distributions
.sp
Most Linux distributions have Sphinx in their package repositories. Usually
the package is called \fBpython3\-sphinx\fP, \fBpython\-sphinx\fP or \fBsphinx\fP\&. Be
aware that there are at least two other packages with \fBsphinx\fP in their name:
a speech recognition toolkit (\fICMU Sphinx\fP) and a full\-text search database
(\fISphinx search\fP).
.SS macOS
.sp
Sphinx can be installed using \X'tty: link https://brew.sh/'\fI\%Homebrew\fP\X'tty: link', \X'tty: link https://www.macports.org/'\fI\%MacPorts\fP\X'tty: link', or as part of
a Python distribution such as \X'tty: link https://www.anaconda.com/download'\fI\%Anaconda\fP\X'tty: link'\&.
.SS Homebrew
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ brew install sphinx\-doc
.EE
.UNINDENT
.UNINDENT
.sp
For more information, refer to the \X'tty: link https://formulae.brew.sh/formula/sphinx-doc'\fI\%package overview\fP\X'tty: link'\&.
.SS MacPorts
.sp
Install either \fBpython3x\-sphinx\fP using \fBport\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ sudo port install py39\-sphinx
.EE
.UNINDENT
.UNINDENT
.sp
To set up the executable paths, use the \fBport select\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ sudo port select \-\-set python python39
$ sudo port select \-\-set sphinx py39\-sphinx
.EE
.UNINDENT
.UNINDENT
.sp
For more information, refer to the \X'tty: link https://www.macports.org/ports.php?by=library&substr=py39-sphinx'\fI\%package overview\fP\X'tty: link'\&.
.SS Anaconda
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ conda install sphinx
.EE
.UNINDENT
.UNINDENT
.SS Windows
.sp
Sphinx can be install using \X'tty: link https://chocolatey.org/'\fI\%Chocolatey\fP\X'tty: link' or
\fI\%installed manually\fP\&.
.SS Chocolatey
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ choco install sphinx
.EE
.UNINDENT
.UNINDENT
.sp
You would need to \X'tty: link https://chocolatey.org/install'\fI\%install Chocolatey\fP\X'tty: link'
before running this.
.sp
For more information, refer to the \X'tty: link https://chocolatey.org/packages/sphinx/'\fI\%chocolatey page\fP\X'tty: link'\&.
.SS Other Methods
.sp
Most Windows users do not have Python installed by default, so we begin with
the installation of Python itself. To check if you already have Python
installed, open the \fICommand Prompt\fP (\fB⊞Win\-r\fP and type \fBcmd\fP).
Once the command prompt is open, type \fBpython \-\-version\fP and press
Enter. If Python is installed, you will see the version of Python printed to
the screen. If you do not have Python installed, refer to the \X'tty: link https://docs.python-guide.org/'\fI\%Hitchhikers
Guide to Python\(aqs\fP\X'tty: link' Python on Windows installation guides. You must install
\X'tty: link https://docs.python-guide.org/starting/install3/win/'\fI\%Python 3\fP\X'tty: link'\&.
.sp
Once Python is installed, you can install Sphinx using \fBpip\fP\&. Refer
to the \fI\%pip installation instructions\fP below for more
information.
.SS Installation from PyPI
.sp
Sphinx packages are published on the \X'tty: link https://pypi.org/project/Sphinx/'\fI\%Python Package Index\fP\X'tty: link'\&. The preferred tool for installing
packages from \fIPyPI\fP is \fBpip\fP\&. This tool is provided with all modern
versions of Python.
.sp
On Linux or MacOS, you should open your terminal and run the following command.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pip install \-U sphinx
.EE
.UNINDENT
.UNINDENT
.sp
On Windows, you should open \fICommand Prompt\fP (\fB⊞Win\-r\fP and type
\fBcmd\fP) and run the same command.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
C:\e> pip install \-U sphinx
.EE
.UNINDENT
.UNINDENT
.sp
After installation, type \fBsphinx\-build \-\-version\fP on the command
prompt. If everything worked fine, you will see the version number for the
Sphinx package you just installed.
.sp
Installation from \fIPyPI\fP also allows you to install the latest development
release. You will not generally need (or want) to do this, but it can be
useful if you see a possible bug in the latest stable release. To do this, use
the \fB\-\-pre\fP flag.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pip install \-U \-\-pre sphinx
.EE
.UNINDENT
.UNINDENT
.SS Using virtual environments
.sp
When installing Sphinx using pip,
it is highly recommended to use \fIvirtual environments\fP,
which isolate the installed packages from the system packages,
thus removing the need to use administrator privileges.
To create a virtual environment in the \fB\&.venv\fP directory,
use the following command.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ python \-m venv .venv
.EE
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
\X'tty: link https://docs.python.org/3/library/venv.html#module-venv'\fI\%venv\fP\X'tty: link' \-\- creating virtual environments
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Note that in some Linux distributions, such as Debian and Ubuntu,
this might require an extra installation step as follows.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ apt\-get install python3\-venv
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SS Docker
.sp
Docker images for Sphinx are published on the \X'tty: link https://hub.docker.com/'\fI\%Docker Hub\fP\X'tty: link'\&. There are two kind
of images:
.INDENT 0.0
.IP \(bu 2
\X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx'\fI\%sphinxdoc/sphinx\fP\X'tty: link'
.IP \(bu 2
\X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx-latexpdf'\fI\%sphinxdoc/sphinx\-latexpdf\fP\X'tty: link'
.UNINDENT
.sp
Former one is used for standard usage of Sphinx, and latter one is mainly used for
PDF builds using LaTeX. Please choose one for your purpose.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
sphinxdoc/sphinx\-latexpdf contains TeXLive packages. So the image is very large
(over 2GB!).
.UNINDENT
.UNINDENT
.sp
\fBHINT:\fP
.INDENT 0.0
.INDENT 3.5
When using docker images, please use \fBdocker run\fP command to invoke sphinx
commands. For example, you can use following command to create a Sphinx
project:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ docker run \-it \-\-rm \-v /path/to/document:/docs sphinxdoc/sphinx sphinx\-quickstart
.EE
.UNINDENT
.UNINDENT
.sp
And you can use the following command to build HTML document:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ docker run \-\-rm \-v /path/to/document:/docs sphinxdoc/sphinx make html
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
For more details, please read \X'tty: link https://hub.docker.com/r/sphinxdoc/sphinx'\fI\%README file\fP\X'tty: link' of docker images.
.SS Installation from source
.sp
You can install Sphinx directly from a clone of the \X'tty: link https://github.com/sphinx-doc/sphinx'\fI\%Git repository\fP\X'tty: link'\&. This
can be done either by cloning the repo and installing from the local clone, on
simply installing directly via \fBgit\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ git clone https://github.com/sphinx\-doc/sphinx
$ cd sphinx
$ pip install .
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ pip install git+https://github.com/sphinx\-doc/sphinx
.EE
.UNINDENT
.UNINDENT
.sp
You can also download a snapshot of the Git repo in either \X'tty: link https://github.com/sphinx-doc/sphinx/archive/master.tar.gz'\fI\%tar.gz\fP\X'tty: link' or
\X'tty: link https://github.com/sphinx-doc/sphinx/archive/master.zip'\fI\%zip\fP\X'tty: link' format. Once downloaded and extracted, these can be installed with
\fBpip\fP as above.
.SS Tutorial: Build your first project
.sp
In this tutorial you will build a simple documentation project using Sphinx, and
view it in your browser as HTML. The project will include narrative,
handwritten documentation, as well as autogenerated API documentation.
.sp
The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
of how projects are created and structured. You will create a fictional
software library to generate random food recipes that will serve as a guide
throughout the process, with the objective of properly documenting it.
.sp
To showcase Sphinx capabilities for code documentation you will use Python,
which also supports \fIautomatic\fP documentation generation.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Several other languages are natively supported in Sphinx for \fImanual\fP code
documentation, however they require extensions for \fIautomatic\fP code
documentation, like \X'tty: link https://breathe.readthedocs.io/'\fI\%Breathe\fP\X'tty: link'\&.
.UNINDENT
.UNINDENT
.sp
To follow the instructions you will need access to a Linux\-like command line and
a basic understanding of how it works, as well as a working Python installation
for development, since you will use \fIPython virtual environments\fP to create the
project.
.SS Getting started
.SS Setting up your project and development environment
.sp
In a new directory, create a file called \fBREADME.rst\fP with the following
content.
.sp
README.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Lumache
=======
**Lumache** (/lu\(aqmake/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.
.EE
.UNINDENT
.UNINDENT
.sp
It is a good moment to create a Python virtual environment and install the
required tools. For that, open a command line terminal, \fBcd\fP into the
directory you just created, and run the following commands:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ python \-m venv .venv
$ source .venv/bin/activate
(.venv) $ python \-m pip install sphinx
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The installation method used above is described in more detail in
\X'tty: link #install-pypi'\fI\%Installation from PyPI\fP\X'tty: link'\&. For the rest of this tutorial, the instructions will
assume a Python virtual environment.
.UNINDENT
.UNINDENT
.sp
If you executed these instructions correctly, you should have the Sphinx command
line tools available. You can do a basic verification running this command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ sphinx\-build \-\-version
sphinx\-build 4.0.2
.EE
.UNINDENT
.UNINDENT
.sp
If you see a similar output, you are on the right path!
.SS Creating the documentation layout
.sp
Then from the command line, run the following command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ sphinx\-quickstart docs
.EE
.UNINDENT
.UNINDENT
.sp
This will present to you a series of questions required to create the basic
directory and configuration layout for your project inside the \fBdocs\fP folder.
To proceed, answer each question as follows:
.INDENT 0.0
.IP \(bu 2
\fB> Separate source and build directories (y/n) [n]\fP: Write \(dq\fBy\fP\(dq (without
quotes) and press \fBEnter\fP\&.
.IP \(bu 2
\fB> Project name\fP: Write \(dq\fBLumache\fP\(dq (without quotes) and press
\fBEnter\fP\&.
.IP \(bu 2
\fB> Author name(s)\fP: Write \(dq\fBGraziella\fP\(dq (without quotes) and press
\fBEnter\fP\&.
.IP \(bu 2
\fB> Project release []\fP: Write \(dq\fB0.1\fP\(dq (without quotes) and press
\fBEnter\fP\&.
.IP \(bu 2
\fB> Project language [en]\fP: Leave it empty (the default, English) and press
\fBEnter\fP\&.
.UNINDENT
.sp
After the last question, you will see the new \fBdocs\fP directory with the
following content.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
docs
├── build
├── make.bat
├── Makefile
└── source
├── conf.py
├── index.rst
├── _static
└── _templates
.EE
.UNINDENT
.UNINDENT
.sp
The purpose of each of these files is:
.INDENT 0.0
.TP
.B \fBbuild/\fP
An empty directory (for now) that will hold the rendered documentation.
.TP
.B \fBmake.bat\fP and \fBMakefile\fP
Convenience scripts to simplify some common Sphinx operations, such as
rendering the content.
.TP
.B \fBsource/conf.py\fP
A Python script holding the configuration of the Sphinx project. It contains
the project name and release you specified to \fBsphinx\-quickstart\fP, as well
as some extra configuration keys.
.TP
.B \fBsource/index.rst\fP
The \X'tty: link #term-root-document'\fI\%root document\fP\X'tty: link' of the project, which serves as welcome page and
contains the root of the \(dqtable of contents tree\(dq (or \fItoctree\fP).
.UNINDENT
.sp
Thanks to this bootstrapping step, you already have everything needed to render
the documentation as HTML for the first time. To do that, run this command:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ sphinx\-build \-M html docs/source/ docs/build/
.EE
.UNINDENT
.UNINDENT
.sp
And finally, open \fBdocs/build/html/index.html\fP in your browser. You should see
something like this:
.INDENT 0.0
.INDENT 2.5
[image: Freshly created documentation of Lumache]
[image]
Freshly created documentation of Lumache.UNINDENT
.UNINDENT
.sp
There we go! You created your first HTML documentation using Sphinx.
Now you can start \fI\%customizing it\fP\&.
.SS First steps to document your project using Sphinx
.SS Building your HTML documentation
.sp
The \fBindex.rst\fP file that \fBsphinx\-quickstart\fP created has some content
already, and it gets rendered as the front page of your HTML documentation. It
is written in reStructuredText, a powerful markup language.
.sp
Modify the file as follows:
.sp
docs/source/index.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Welcome to Lumache\(aqs documentation!
===================================
**Lumache** (/lu\(aqmake/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients. It pulls data from the \(gaOpen Food
Facts database \(ga_ and offers a *simple* and
*intuitive* API.
\&.. note::
This project is under active development.
.EE
.UNINDENT
.UNINDENT
.sp
This showcases several features of the reStructuredText syntax, including:
.INDENT 0.0
.IP \(bu 2
a \fBsection header\fP using \fB===\fP for the underline,
.IP \(bu 2
two examples of \X'tty: link #rst-inline-markup'\fI\%Inline markup\fP\X'tty: link': \fB**strong emphasis**\fP (typically
bold) and \fB*emphasis*\fP (typically italics),
.IP \(bu 2
an \fBinline external link\fP,
.IP \(bu 2
and a \fBnote\fP \fBadmonition\fP (one of the available \X'tty: link #rst-directives'\fI\%directives\fP\X'tty: link')
.UNINDENT
.sp
Now to render it with the new content, you can use the \fBsphinx\-build\fP command
as before, or leverage the convenience script as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ cd docs
(.venv) $ make html
.EE
.UNINDENT
.UNINDENT
.sp
After running this command, you will see that \fBindex.html\fP reflects the new
changes!
.SS Building your documentation in other formats
.sp
Sphinx supports a variety of formats apart from HTML, including PDF, EPUB,
\X'tty: link #builders'\fI\%and more\fP\X'tty: link'\&. For example, to build your documentation
in EPUB format, run this command from the \fBdocs\fP directory:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ make epub
.EE
.UNINDENT
.UNINDENT
.sp
After that, you will see the files corresponding to the e\-book under
\fBdocs/build/epub/\fP\&. You can either open \fBLumache.epub\fP with an
EPUB\-compatible e\-book viewer, like \X'tty: link https://calibre-ebook.com/'\fI\%Calibre\fP\X'tty: link',
or preview \fBindex.xhtml\fP on a web browser.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To quickly display a complete list of possible output formats, plus some
extra useful commands, you can run \fBmake help\fP\&.
.UNINDENT
.UNINDENT
.sp
Each output format has some specific configuration options that you can tune,
\X'tty: link #epub-options'\fI\%including EPUB\fP\X'tty: link'\&. For instance, the default value of
\X'tty: link #confval-epub_show_urls'\fI\%epub_show_urls\fP\X'tty: link' is \fBinline\fP, which means that, by default, URLs are
shown right after the corresponding link, in parentheses. You can change that
behavior by adding the following code at the end of your \fBconf.py\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# EPUB options
epub_show_urls = \(aqfootnote\(aq
.EE
.UNINDENT
.UNINDENT
.sp
With this configuration value, and after running \fBmake epub\fP again, you will
notice that URLs appear now as footnotes, which avoids cluttering the text.
Sweet! Read on to explore \fI\%other ways to customize
Sphinx\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Generating a PDF using Sphinx can be done running \fBmake latexpdf\fP,
provided that the system has a working LaTeX installation,
as explained in the documentation of \X'tty: link #sphinx.builders.latex.LaTeXBuilder'\fI\%sphinx.builders.latex.LaTeXBuilder\fP\X'tty: link'\&.
Although this is perfectly feasible, such installations are often big,
and in general LaTeX requires careful configuration in some cases,
so PDF generation is out of scope for this tutorial.
.UNINDENT
.UNINDENT
.SS More Sphinx customization
.sp
There are two main ways to customize your documentation beyond what is possible
with core Sphinx: extensions and themes.
.SS Enabling a built\-in extension
.sp
In addition to these configuration values, you can customize Sphinx even more
by using \fI\%extensions\fP\&. Sphinx ships several
\X'tty: link #builtin-extensions'\fI\%builtin ones\fP\X'tty: link', and there are many more
\X'tty: link #third-party-extensions'\fI\%maintained by the community\fP\X'tty: link'\&.
.sp
For example, to enable the \X'tty: link #module-sphinx.ext.duration'\fI\%sphinx.ext.duration\fP\X'tty: link' extension,
locate the \fBextensions\fP list in your \fBconf.py\fP and add one element as
follows:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named \(aqsphinx.ext.*\(aq) or your custom
# ones.
extensions = [
\(aqsphinx.ext.duration\(aq,
]
.EE
.UNINDENT
.UNINDENT
.sp
After that, every time you generate your documentation, you will see a short
durations report at the end of the console output, like this one:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ make html
\&...
The HTML pages are in build/html.
====================== slowest reading durations =======================
0.042 temp/source/index
.EE
.UNINDENT
.UNINDENT
.SS Using a third\-party HTML theme
.sp
Themes, on the other hand, are a way to customize the appearance of your
documentation. Sphinx has several \X'tty: link #builtin-themes'\fI\%builtin themes\fP\X'tty: link', and
there are also \X'tty: link https://sphinx-themes.org/'\fI\%third\-party ones\fP\X'tty: link'\&.
.sp
For example, to use the \X'tty: link https://pradyunsg.me/furo/'\fI\%Furo\fP\X'tty: link' third\-party theme
in your HTML documentation, first you will need to install it with \fBpip\fP in
your Python virtual environment, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ pip install furo
.EE
.UNINDENT
.UNINDENT
.sp
And then, locate the \fBhtml_theme\fP variable on your \fBconf.py\fP and replace
its value as follows:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = \(aqfuro\(aq
.EE
.UNINDENT
.UNINDENT
.sp
With this change, you will notice that your HTML documentation has now a new
appearance:
.INDENT 0.0
.INDENT 2.5
[image: HTML documentation of Lumache with the Furo theme]
[image]
HTML documentation of Lumache with the Furo theme.UNINDENT
.UNINDENT
.sp
It is now time to \fI\%expand the narrative documentation and split it into
several documents\fP\&.
.SS Narrative documentation in Sphinx
.SS Structuring your documentation across multiple pages
.sp
The file \fBindex.rst\fP created by \fBsphinx\-quickstart\fP is the \X'tty: link #term-root-document'\fI\%root
document\fP\X'tty: link', whose main function is to serve as a welcome page and to contain the
root of the \(dqtable of contents tree\(dq (or \fItoctree\fP). Sphinx allows you to
assemble a project from different files, which is helpful when the project
grows.
.sp
As an example, create a new file \fBdocs/source/usage.rst\fP (next to
\fBindex.rst\fP) with these contents:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Usage
=====
Installation
\-\-\-\-\-\-\-\-\-\-\-\-
To use Lumache, first install it using pip:
\&.. code\-block:: console
(.venv) $ pip install lumache
.EE
.UNINDENT
.UNINDENT
.sp
This new file contains two \X'tty: link #rst-sections'\fI\%section\fP\X'tty: link' headers, normal
paragraph text, and a \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive that renders
a block of content as source code, with appropriate syntax highlighting
(in this case, generic \fBconsole\fP text).
.sp
The structure of the document is determined by the succession of heading
styles, which means that, by using \fB\-\-\-\fP for the \(dqInstallation\(dq section
after \fB===\fP for the \(dqUsage\(dq section, you have declared \(dqInstallation\(dq to
be a \fIsubsection\fP of \(dqUsage\(dq.
.sp
To complete the process, add a \fBtoctree\fP \X'tty: link #rst-directives'\fI\%directive\fP\X'tty: link' at
the end of \fBindex.rst\fP including the document you just created, as follows:
.sp
docs/source/index.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Contents
\-\-\-\-\-\-\-\-
\&.. toctree::
usage
.EE
.UNINDENT
.UNINDENT
.sp
This step inserts that document in the root of the \fItoctree\fP, so now it belongs
to the structure of your project, which so far looks like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
index
└── usage
.EE
.UNINDENT
.UNINDENT
.sp
If you build the HTML documentation running \fBmake html\fP, you will see
that the \fBtoctree\fP gets rendered as a list of hyperlinks, and this allows you
to navigate to the new page you just created. Neat!
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Documents outside a \fItoctree\fP will result in \fBWARNING: document isn\(aqt
included in any toctree\fP messages during the build process, and will be
unreachable for users.
.UNINDENT
.UNINDENT
.SS Adding cross\-references
.sp
One powerful feature of Sphinx is the ability to seamlessly add
\X'tty: link #xref-syntax'\fI\%cross\-references\fP\X'tty: link' to specific parts of the documentation:
a document, a section, a figure, a code object, etc. This tutorial is full of
them!
.sp
To add a cross\-reference, write this sentence right after the
introduction paragraph in \fBindex.rst\fP:
.sp
docs/source/index.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Check out the :doc:\(gausage\(ga section for further information.
.EE
.UNINDENT
.UNINDENT
.sp
The \X'tty: link #role-doc'\fI\%doc\fP\X'tty: link' \X'tty: link #rst-roles-alt'\fI\%role\fP\X'tty: link' you used automatically
references a specific document in the project, in this case the \fBusage.rst\fP
you created earlier.
.sp
Alternatively, you can also add a cross\-reference to an arbitrary part of the
project. For that, you need to use the \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' role, and add an
explicit \fIlabel\fP that acts as \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets'\fI\%a target\fP\X'tty: link'\&.
.sp
For example, to reference the \(dqInstallation\(dq subsection, add a label right
before the heading, as follows:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Usage
=====
\&.. _installation:
Installation
\-\-\-\-\-\-\-\-\-\-\-\-
\&...
.EE
.UNINDENT
.UNINDENT
.sp
And make the sentence you added in \fBindex.rst\fP look like this:
.sp
docs/source/index.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Check out the :doc:\(gausage\(ga section for further information, including how to
:ref:\(gainstall \(ga the project.
.EE
.UNINDENT
.UNINDENT
.sp
Notice a trick here: the \fBinstall\fP part specifies how the link will look like
(we want it to be a specific word, so the sentence makes sense), whereas the
\fB\fP part refers to the actual label we want to add a
cross\-reference to. If you do not include an explicit title, hence using
\fB:ref:\(gainstallation\(ga\fP, the section title will be used (in this case,
\fBInstallation\fP). Both the \fB:doc:\fP and the \fB:ref:\fP roles will be rendered
as hyperlinks in the HTML documentation.
.sp
What about \fI\%documenting code objects in Sphinx\fP?
Read on!
.SS Describing code in Sphinx
.sp
In the \fI\%previous sections of the tutorial\fP you can read
how to write narrative or prose documentation in Sphinx. In this section you
will describe code objects instead.
.sp
Sphinx supports documenting code objects in several languages, namely Python,
C, C++, JavaScript, and reStructuredText. Each of them can be documented using
a series of directives and roles grouped by
\fI\%domain\fP\&. For the remainder of the
tutorial you will use the Python domain, but all the concepts seen in this
section apply for the other domains as well.
.SS Python
.SS Documenting Python objects
.sp
Sphinx offers several roles and directives to document Python objects,
all grouped together in \fI\%the Python domain\fP\&.
For example, you can use the \X'tty: link #directive-py-function'\fI\%py:function\fP\X'tty: link' directive to document
a Python function, as follows:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Creating recipes
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
To retrieve a list of random ingredients,
you can use the \(ga\(galumache.get_random_ingredients()\(ga\(ga function:
\&.. py:function:: lumache.get_random_ingredients(kind=None)
Return a list of random ingredients as strings.
:param kind: Optional \(dqkind\(dq of ingredients.
:type kind: list[str] or None
:return: The ingredients list.
:rtype: list[str]
.EE
.UNINDENT
.UNINDENT
.sp
Which will render like this:
.INDENT 0.0
.INDENT 2.5
[image: HTML result of documenting a Python function in Sphinx]
[image]
The rendered result of documenting a Python function in Sphinx.UNINDENT
.UNINDENT
.sp
Notice several things:
.INDENT 0.0
.IP \(bu 2
Sphinx parsed the argument of the \fB\&.. py:function\fP directive and
highlighted the module, the function name, and the parameters appropriately.
.IP \(bu 2
The directive content includes a one\-line description of the function,
as well as an \X'tty: link #info-field-lists'\fI\%info field list\fP\X'tty: link' containing the function
parameter, its expected type, the return value, and the return type.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The \fBpy:\fP prefix specifies the \X'tty: link #term-domain'\fI\%domain\fP\X'tty: link'\&. You may configure the
default domain so you can omit the prefix, either globally using the
\X'tty: link #confval-primary_domain'\fI\%primary_domain\fP\X'tty: link' configuration, or use the
\X'tty: link #directive-default-domain'\fI\%default\-domain\fP\X'tty: link' directive to change it from the point it is called
until the end of the file.
For example, if you set it to \fBpy\fP (the default), you can write
\fB\&.. function::\fP directly.
.UNINDENT
.UNINDENT
.SS Cross\-referencing Python objects
.sp
By default, most of these directives generate entities that can be
cross\-referenced from any part of the documentation by using
\X'tty: link #python-roles'\fI\%a corresponding role\fP\X'tty: link'\&. For the case of functions,
you can use \X'tty: link #role-py-func'\fI\%py:func\fP\X'tty: link' for that, as follows:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
The \(ga\(gakind\(ga\(ga parameter should be either \(ga\(ga\(dqmeat\(dq\(ga\(ga, \(ga\(ga\(dqfish\(dq\(ga\(ga,
or \(ga\(ga\(dqveggies\(dq\(ga\(ga. Otherwise, :py:func:\(galumache.get_random_ingredients\(ga
will raise an exception.
.EE
.UNINDENT
.UNINDENT
.sp
When generating code documentation, Sphinx will generate a
cross\-reference automatically just by using the name of the object,
without you having to explicitly use a role for that. For example, you
can describe the custom exception raised by the function using the
\X'tty: link #directive-py-exception'\fI\%py:exception\fP\X'tty: link' directive:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. py:exception:: lumache.InvalidKindError
Raised if the kind is invalid.
.EE
.UNINDENT
.UNINDENT
.sp
Then, add this exception to the original description of the function:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. py:function:: lumache.get_random_ingredients(kind=None)
Return a list of random ingredients as strings.
:param kind: Optional \(dqkind\(dq of ingredients.
:type kind: list[str] or None
:raise lumache.InvalidKindError: If the kind is invalid.
:return: The ingredients list.
:rtype: list[str]
.EE
.UNINDENT
.UNINDENT
.sp
And finally, this is how the result would look:
.INDENT 0.0
.INDENT 2.5
[image: HTML result of documenting a Python function in Sphinx
with cross-references]
[image]
HTML result of documenting a Python function in Sphinx with cross\-references.UNINDENT
.UNINDENT
.sp
Beautiful, isn\(aqt it?
.SS Including doctests in your documentation
.sp
Since you are now describing code from a Python library, it will become useful
to keep both the documentation and the code as synchronized as possible.
One of the ways to do that in Sphinx is to include code snippets in the
documentation, called \fIdoctests\fP, that are executed when the documentation is
built.
.sp
To demonstrate doctests and other Sphinx features covered in this tutorial,
Sphinx will need to be able to import the code. To achieve that, write this
at the beginning of \fBconf.py\fP:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here.
import pathlib
import sys
sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
An alternative to changing the \X'tty: link https://docs.python.org/3/library/sys.html#sys.path'\fI\%sys.path\fP\X'tty: link' variable is to create a
\fBpyproject.toml\fP file and make the code installable,
so it behaves like any other Python library. However, the \fBsys.path\fP
approach is simpler.
.UNINDENT
.UNINDENT
.sp
Then, before adding doctests to your documentation, enable the
\fI\%doctest\fP extension in \fBconf.py\fP:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
extensions = [
\(aqsphinx.ext.duration\(aq,
\(aqsphinx.ext.doctest\(aq,
]
.EE
.UNINDENT
.UNINDENT
.sp
Next, write a doctest block as follows:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> import lumache
>>> lumache.get_random_ingredients()
[\(aqshells\(aq, \(aqgorgonzola\(aq, \(aqparsley\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
Doctests include the Python instructions to be run preceded by \fB>>>\fP,
the standard Python interpreter prompt, as well as the expected output
of each instruction. This way, Sphinx can check whether the actual output
matches the expected one.
.sp
To observe how a doctest failure looks like (rather than a code error as
above), let\(aqs write the return value incorrectly first. Therefore, add a
function \fBget_random_ingredients\fP like this:
.sp
lumache.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def get_random_ingredients(kind=None):
return [\(dqeggs\(dq, \(dqbacon\(dq, \(dqspam\(dq]
.EE
.UNINDENT
.UNINDENT
.sp
You can now run \fBmake doctest\fP to execute the doctests of your documentation.
Initially this will display an error, since the actual code does not behave
as specified:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
(.venv) $ make doctest
Running Sphinx v4.2.0
loading pickled environment... done
\&...
running tests...
Document: usage
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
**********************************************************************
File \(dqusage.rst\(dq, line 44, in default
Failed example:
lumache.get_random_ingredients()
Expected:
[\(aqshells\(aq, \(aqgorgonzola\(aq, \(aqparsley\(aq]
Got:
[\(aqeggs\(aq, \(aqbacon\(aq, \(aqspam\(aq]
**********************************************************************
\&...
make: *** [Makefile:20: doctest] Error 1
.EE
.UNINDENT
.UNINDENT
.sp
As you can see, doctest reports the expected and the actual results,
for easy examination. It is now time to fix the function:
.sp
lumache.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def get_random_ingredients(kind=None):
return [\(dqshells\(dq, \(dqgorgonzola\(dq, \(dqparsley\(dq]
.EE
.UNINDENT
.UNINDENT
.sp
And finally, \fBmake doctest\fP reports success!
.sp
For big projects though, this manual approach can become a bit tedious.
In the next section, you will see \fI\%how to automate the
process\fP\&.
.SS Other languages (C, C++, others)
.SS Documenting and cross\-referencing objects
.sp
Sphinx also supports documenting and cross\-referencing objects written in
other programming languages. There are four additional built\-in domains:
C, C++, JavaScript, and reStructuredText. Third\-party extensions may
define domains for more languages, such as
.INDENT 0.0
.IP \(bu 2
\X'tty: link https://sphinx-fortran.readthedocs.io'\fI\%Fortran\fP\X'tty: link',
.IP \(bu 2
\X'tty: link https://bastikr.github.io/sphinx-julia'\fI\%Julia\fP\X'tty: link', or
.IP \(bu 2
\X'tty: link https://github.com/markstory/sphinxcontrib-phpdomain'\fI\%PHP\fP\X'tty: link'\&.
.UNINDENT
.sp
For example, to document a C++ type definition, you would use the built\-in
\X'tty: link #directive-cpp-type'\fI\%cpp:type\fP\X'tty: link' directive, as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. cpp:type:: std::vector CustomList
A typedef\-like declaration of a type.
.EE
.UNINDENT
.UNINDENT
.sp
Which would give the following result:
.INDENT 0.0
.TP
.B typedef std::vector CustomList
A typedef\-like declaration of a type.
.UNINDENT
.sp
All such directives then generate references that can be
cross\-referenced by using the corresponding role. For example, to reference
the previous type definition, you can use the \X'tty: link #role-cpp-type'\fI\%cpp:type\fP\X'tty: link' role
as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Cross reference to :cpp:type:\(gaCustomList\(ga.
.EE
.UNINDENT
.UNINDENT
.sp
Which would produce a hyperlink to the previous definition: \fI\%CustomList\fP\&.
.SS Automatic documentation generation from code
.sp
In the \X'tty: link #tutorial-describing-objects'\fI\%previous section\fP\X'tty: link' of the tutorial
you manually documented a Python function in Sphinx. However, the description
was out of sync with the code itself, since the function signature was not
the same. Besides, it would be nice to reuse \X'tty: link https://peps.python.org/pep-0257/#what-is-a-docstring'\fI\%Python docstrings\fP\X'tty: link' in the documentation, rather than having to write
the information in two places.
.sp
Fortunately, \fI\%the autodoc extension\fP provides this
functionality.
.SS Reusing signatures and docstrings with autodoc
.sp
To use autodoc, first add it to the list of enabled extensions:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
extensions = [
\(aqsphinx.ext.duration\(aq,
\(aqsphinx.ext.doctest\(aq,
\(aqsphinx.ext.autodoc\(aq,
]
.EE
.UNINDENT
.UNINDENT
.sp
Next, move the content of the \fB\&.. py:function\fP directive to the function
docstring in the original Python file, as follows:
.sp
lumache.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def get_random_ingredients(kind=None):
\(dq\(dq\(dq
Return a list of random ingredients as strings.
:param kind: Optional \(dqkind\(dq of ingredients.
:type kind: list[str] or None
:raise lumache.InvalidKindError: If the kind is invalid.
:return: The ingredients list.
:rtype: list[str]
\(dq\(dq\(dq
return [\(dqshells\(dq, \(dqgorgonzola\(dq, \(dqparsley\(dq]
.EE
.UNINDENT
.UNINDENT
.sp
Finally, replace the \fB\&.. py:function\fP directive from the Sphinx documentation
with \X'tty: link #directive-autofunction'\fI\%autofunction\fP\X'tty: link':
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
you can use the \(ga\(galumache.get_random_ingredients()\(ga\(ga function:
\&.. autofunction:: lumache.get_random_ingredients
.EE
.UNINDENT
.UNINDENT
.sp
If you now build the HTML documentation, the output will be the same!
With the advantage that it is generated from the code itself.
Sphinx took the reStructuredText from the docstring and included it,
also generating proper cross\-references.
.sp
You can also autogenerate documentation from other objects. For example, add
the code for the \fBInvalidKindError\fP exception:
.sp
lumache.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
class InvalidKindError(Exception):
\(dq\(dq\(dqRaised if the kind is invalid.\(dq\(dq\(dq
pass
.EE
.UNINDENT
.UNINDENT
.sp
And replace the \fB\&.. py:exception\fP directive with \X'tty: link #directive-autoexception'\fI\%autoexception\fP\X'tty: link'
as follows:
.sp
docs/source/usage.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
or \(ga\(ga\(dqveggies\(dq\(ga\(ga. Otherwise, :py:func:\(galumache.get_random_ingredients\(ga
will raise an exception.
\&.. autoexception:: lumache.InvalidKindError
.EE
.UNINDENT
.UNINDENT
.sp
And again, after running \fBmake html\fP, the output will be the same as before.
.SS Generating comprehensive API references
.sp
While using \fBsphinx.ext.autodoc\fP makes keeping the code and the documentation
in sync much easier, it still requires you to write an \fBauto*\fP directive
for every object you want to document. Sphinx provides yet another level of
automation: the \fI\%autosummary\fP extension.
.sp
The \X'tty: link #directive-autosummary'\fI\%autosummary\fP\X'tty: link' directive generates documents that contain all the
necessary \fBautodoc\fP directives. To use it, first enable the autosummary
extension:
.sp
docs/source/conf.py
.INDENT 0.0
.INDENT 3.5
.sp
.EX
extensions = [
\(aqsphinx.ext.duration\(aq,
\(aqsphinx.ext.doctest\(aq,
\(aqsphinx.ext.autodoc\(aq,
\(aqsphinx.ext.autosummary\(aq,
]
.EE
.UNINDENT
.UNINDENT
.sp
Next, create a new \fBapi.rst\fP file with these contents:
.sp
docs/source/api.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
API
===
\&.. autosummary::
:toctree: generated
lumache
.EE
.UNINDENT
.UNINDENT
.sp
Remember to include the new document in the root toctree:
.sp
docs/source/index.rst
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Contents
\-\-\-\-\-\-\-\-
\&.. toctree::
usage
api
.EE
.UNINDENT
.UNINDENT
.sp
Finally, after you build the HTML documentation running \fBmake html\fP, it will
contain two new pages:
.INDENT 0.0
.IP \(bu 2
\fBapi.html\fP, corresponding to \fBdocs/source/api.rst\fP and containing a table
with the objects you included in the \fBautosummary\fP directive (in this case,
only one).
.IP \(bu 2
\fBgenerated/lumache.html\fP, corresponding to a newly created reST file
\fBgenerated/lumache.rst\fP and containing a summary of members of the module,
in this case one function and one exception.
.UNINDENT
.INDENT 0.0
.INDENT 2.5
[image: Summary page created by autosummary]
[image]
Summary page created by autosummary.UNINDENT
.UNINDENT
.sp
Each of the links in the summary page will take you to the places where you
originally used the corresponding \fBautodoc\fP directive, in this case in the
\fBusage.rst\fP document.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The generated files are based on \X'tty: link https://jinja.palletsprojects.com/'\fI\%Jinja2
templates\fP\X'tty: link' that
\X'tty: link #autosummary-customizing-templates'\fI\%can be customized\fP\X'tty: link',
but that is out of scope for this tutorial.
.UNINDENT
.UNINDENT
.SS Appendix: Deploying a Sphinx project online
.sp
When you are ready to show your documentation project to the world, there are
many options available to do so. Since the HTML generated by Sphinx is static,
you can decouple the process of building your HTML documentation from hosting
such files in the platform of your choice. You will not need a sophisticated
server running Python: virtually every web hosting service will suffice.
.sp
Therefore, the challenge is less how or where to serve the static HTML, but
rather how to pick a workflow that automatically updates the deployed
documentation every time there is a change in the source files.
.sp
The following sections describe some of the available options to deploy
your online documentation, and give some background information. If you want
to go directly to the practical part, you can skip to \fI\%Publishing your documentation sources\fP\&.
.SS Sphinx\-friendly deployment options
.sp
There are several possible options you have to host your Sphinx documentation.
Some of them are:
.INDENT 0.0
.TP
\fBRead the Docs\fP
\X'tty: link https://readthedocs.org/'\fI\%Read the Docs\fP\X'tty: link' is an online service specialized in hosting technical
documentation written in Sphinx, as well as MkDocs. They have a
number of extra features, such as versioned documentation, traffic and
search analytics, custom domains, user\-defined redirects, and more.
.TP
\fBGitHub Pages\fP
\X'tty: link https://pages.github.com/'\fI\%GitHub Pages\fP\X'tty: link' is a simple static web hosting tightly integrated with
\X'tty: link https://github.com/'\fI\%GitHub\fP\X'tty: link': static HTML is served from one of the branches of a project,
and usually sources are stored in another branch so that the output
can be updated every time the sources change (for example using \X'tty: link https://github.com/features/actions'\fI\%GitHub
Actions\fP\X'tty: link'). It is free to use and supports custom domains.
.TP
\fBGitLab Pages\fP
\X'tty: link https://about.gitlab.com/stages-devops-lifecycle/pages/'\fI\%GitLab Pages\fP\X'tty: link' is a similar concept to GitHub Pages, integrated with
\X'tty: link https://gitlab.com/'\fI\%GitLab\fP\X'tty: link' and usually automated with \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/'\fI\%GitLab CI\fP\X'tty: link' instead.
.TP
\fBNetlify\fP
\X'tty: link https://www.netlify.com/'\fI\%Netlify\fP\X'tty: link' is a sophisticated hosting for static sites enhanced by
client\-side web technologies like JavaScript (so\-called \X'tty: link https://jamstack.org/'\fI\%\(dqJamstack\(dq\fP\X'tty: link').
They offer support for headless content management systems and
serverless computing.
.TP
\fBYour own server\fP
You can always use your own web server to host Sphinx HTML documentation.
It is the option that gives more flexibility, but also more complexity.
.UNINDENT
.sp
All these options have zero cost, with the option of paying for extra features.
.SS Embracing the \(dqDocs as Code\(dq philosophy
.sp
The free offerings of most of the options listed above require your
documentation sources to be publicly available. Moreover, these services
expect you to use a \X'tty: link https://en.wikipedia.org/wiki/Version_control'\fI\%Version Control System\fP\X'tty: link', a technology that tracks the
evolution of a collection of files as a series of snapshots (\(dqcommits\(dq).
The practice of writing documentation in plain text files with the same tools
as the ones used for software development is commonly known as \X'tty: link https://www.writethedocs.org/guide/docs-as-code/'\fI\%\(dqDocs as Code\(dq\fP\X'tty: link'\&.
.sp
The most popular Version Control System nowadays is \X'tty: link https://git-scm.com/'\fI\%Git\fP\X'tty: link', a free and open
source tool that is the backbone of services like GitHub and GitLab.
Since both Read the Docs and Netlify have integrations with GitHub and GitLab,
and both GitHub and GitLab have an integrated Pages product, the most effective
way of automatically build your documentation online is to upload your sources
to either of these Git hosting services.
.SS Publishing your documentation sources
.SS GitHub
.sp
The quickest way to upload an existing project to GitHub is to:
.INDENT 0.0
.IP 1. 3
\X'tty: link https://github.com/signup'\fI\%Sign up for a GitHub account\fP\X'tty: link'\&.
.IP 2. 3
\X'tty: link https://github.com/new'\fI\%Create a new repository\fP\X'tty: link'\&.
.IP 3. 3
Open \X'tty: link https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository'\fI\%the \(dqUpload files\(dq page\fP\X'tty: link' of your new repository.
.IP 4. 3
Select the files on your operating system file browser (in your case
\fBREADME.rst\fP, \fBlumache.py\fP, the makefiles under the \fBdocs\fP directory,
and everything under \fBdocs/source\fP) and drag them to the GitHub interface
to upload them all.
.IP 5. 3
Click on the Commit changes button.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Make sure you don\(aqt upload the \fBdocs/build\fP directory, as it contains the
output generated by Sphinx and it will change every time you change the
sources, complicating your workflow.
.UNINDENT
.UNINDENT
.sp
These steps do not require access to the command line or installing any
additional software. To learn more, read \X'tty: link https://docs.github.com/en/get-started/quickstart'\fI\%this quickstart tutorial\fP\X'tty: link' or
consult the \X'tty: link https://docs.github.com/en/get-started'\fI\%official GitHub documentation\fP\X'tty: link'
.SS GitLab
.sp
Similarly to GitHub, the fastest way to upload your project to GitLab is
using the web interface:
.INDENT 0.0
.IP 1. 3
\X'tty: link https://gitlab.com/users/sign_up'\fI\%Sign up for a GitLab account\fP\X'tty: link'\&.
.IP 2. 3
\X'tty: link https://gitlab.com/projects/new'\fI\%Create a new blank project\fP\X'tty: link'\&.
.IP 3. 3
Upload the project files (in your case \fBREADME.rst\fP, \fBlumache.py\fP, the
makefiles under the \fBdocs\fP directory, and everything under
\fBdocs/source\fP) one by one using the Upload File button [1]\&.
.UNINDENT
.sp
Again, these steps do not require additional software on your computer. To
learn more, you can:
.INDENT 0.0
.IP \(bu 2
Follow \X'tty: link https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html'\fI\%this tutorial\fP\X'tty: link' to install Git on your machine.
.IP \(bu 2
Browse the \X'tty: link https://docs.gitlab.com/ee/user/index.html'\fI\%GitLab User documentation\fP\X'tty: link' to understand the possibilities of
the platform.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Make sure you don\(aqt upload the \fBdocs/build\fP directory, as it contains the
output generated by Sphinx and it will change every time you change the
sources, complicating your workflow.
.UNINDENT
.UNINDENT
.IP [1] 5
At the time of writing, \X'tty: link https://gitlab.com/gitlab-org/gitlab/-/issues/228490'\fI\%uploading whole directories to GitLab using
only the web
interface\fP\X'tty: link' is
not yet implemented.
.SS Publishing your HTML documentation
.SS Read the Docs
.sp
\X'tty: link https://readthedocs.org/'\fI\%Read the Docs\fP\X'tty: link' offers integration with both GitHub and GitLab. The quickest
way of getting started is to follow \X'tty: link https://docs.readthedocs.io/en/stable/tutorial/index.html'\fI\%the RTD
tutorial\fP\X'tty: link', which is loosely based on this one.
You can publish your sources on GitHub as explained \fI\%in the previous
section\fP, then skip directly to
\X'tty: link https://docs.readthedocs.io/en/stable/tutorial/index.html#sign-up-for-read-the-docs'\fI\%Sign up for Read the Docs\fP\X'tty: link'\&.
If you choose GitLab instead, the process is similar.
.SS GitHub Pages
.sp
\X'tty: link https://pages.github.com/'\fI\%GitHub Pages\fP\X'tty: link' requires you to \fI\%publish your
sources\fP on \X'tty: link https://github.com/'\fI\%GitHub\fP\X'tty: link'\&. After that, you will need an
automated process that performs the \fBmake html\fP step every time the sources
change. That can be achieved using \X'tty: link https://github.com/features/actions'\fI\%GitHub Actions\fP\X'tty: link'\&.
.sp
After you have published your sources on GitHub, create a file named
\fB\&.github/workflows/sphinx.yml\fP in your repository with the following
contents:
.sp
\&.github/workflows/
.INDENT 0.0
.INDENT 3.5
.sp
.EX
name: \(dqSphinx: Render docs\(dq
on: push
jobs:
build:
runs\-on: ubuntu\-latest
permissions:
contents: write
steps:
\- uses: actions/checkout@v4
\- name: Build HTML
uses: ammaraskar/sphinx\-action@master
\- name: Upload artifacts
uses: actions/upload\-artifact@v4
with:
name: html\-docs
path: docs/build/html/
\- name: Deploy
uses: peaceiris/actions\-gh\-pages@v3
if: github.ref == \(aqrefs/heads/main\(aq
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/build/html
.EE
.UNINDENT
.UNINDENT
.sp
This contains a GitHub Actions workflow with a single job of four steps:
.INDENT 0.0
.IP 1. 3
Checkout the code.
.IP 2. 3
Build the HTML documentation using Sphinx.
.IP 3. 3
Attach the HTML output the artifacts to the GitHub Actions job, for easier
inspection.
.IP 4. 3
If the change happens on the default branch, take the contents of
\fBdocs/build/html\fP and push it to the \fBgh\-pages\fP branch.
.UNINDENT
.sp
Next, you need to specify the dependencies for the \fBmake html\fP step to be
successful. For that, create a file \fBdocs/requirements.txt\fP and add the
following contents:
.sp
docs/requirements.txt
.INDENT 0.0
.INDENT 3.5
.sp
.EX
furo==2021.11.16
.EE
.UNINDENT
.UNINDENT
.sp
And finally, you are ready to \X'tty: link https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site'\fI\%enable GitHub Pages on your repository\fP\X'tty: link'\&. For
that, go to Settings, then Pages on the left sidebar,
select the \fBgh\-pages\fP branch in the \(dqSource\(dq dropdown menu, and click
Save\&. After a few minutes, you should be able to see your HTML at
the designated URL.
.SS GitLab Pages
.sp
\X'tty: link https://about.gitlab.com/stages-devops-lifecycle/pages/'\fI\%GitLab Pages\fP\X'tty: link', on the other hand, requires you to \fI\%publish your
sources\fP on \X'tty: link https://gitlab.com/'\fI\%GitLab\fP\X'tty: link'\&. When you are ready, you can
automate the process of running \fBmake html\fP using \X'tty: link https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/'\fI\%GitLab CI\fP\X'tty: link'\&.
.sp
After you have published your sources on GitLab, create a file named
\fB\&.gitlab\-ci.yml\fP in your repository with these contents:
.sp
\&.gitlab\-ci.yml
.INDENT 0.0
.INDENT 3.5
.sp
.EX
stages:
\- deploy
pages:
stage: deploy
image: python:3.9\-slim
before_script:
\- apt\-get update && apt\-get install make \-\-no\-install\-recommends \-y
\- python \-m pip install sphinx furo
script:
\- cd docs && make html
after_script:
\- mv docs/build/html/ ./public/
artifacts:
paths:
\- public
rules:
\- if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
.EE
.UNINDENT
.UNINDENT
.sp
This contains a GitLab CI workflow with one job of several steps:
.INDENT 0.0
.IP 1. 3
Install the necessary dependencies.
.IP 2. 3
Build the HTML documentation using Sphinx.
.IP 3. 3
Move the output to a known artifacts location.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
You will need to \X'tty: link https://about.gitlab.com/blog/2021/05/17/prevent-crypto-mining-abuse/#validating-an-account'\fI\%validate your account\fP\X'tty: link' by entering a payment method
(you will be charged a small amount that will then be reimbursed).
.UNINDENT
.UNINDENT
.sp
After that, if the pipeline is successful, you should be able to see your HTML
at the designated URL.
.SS Where to go from here
.sp
This tutorial covered the very first steps to create a documentation project
with Sphinx. To continue learning more about Sphinx, check out the \X'tty: link ../contents.html'\fI\%rest of the
documentation\fP\X'tty: link'\&.
.SH USER GUIDES
.sp
These sections cover various topics in using and extending Sphinx for various
use\-cases. They are a comprehensive guide to using Sphinx in many contexts and
assume more knowledge of Sphinx. If you are new to Sphinx, we recommend
starting with \fI\%Get started\fP\&.
.SS Using Sphinx
.sp
This guide serves to demonstrate how one can get started with Sphinx and covers
everything from installing Sphinx and configuring your first Sphinx project to
using some of the advanced features Sphinx provides out\-of\-the\-box. If you are
looking for guidance on extending Sphinx, refer to \fI\%Writing Sphinx Extensions\fP\&.
.SS reStructuredText
.sp
reStructuredText (reST) is the default plaintext markup language used by both
Docutils and Sphinx. Docutils provides the basic reStructuredText syntax, while
Sphinx extends this to support additional functionality.
.sp
The below guides go through the most important aspects of reST. For the
authoritative reStructuredText reference, refer to the \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%docutils
documentation\fP\X'tty: link'\&.
.SS reStructuredText Primer
.sp
reStructuredText is the default plaintext markup language used by Sphinx. This
section is a brief introduction to reStructuredText (reST) concepts and syntax,
intended to provide authors with enough information to author documents
productively. Since reST was designed to be a simple, unobtrusive markup
language, this will not take too long.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
The authoritative \X'tty: link https://docutils.sourceforge.io/rst.html'\fI\%reStructuredText User Documentation\fP\X'tty: link'\&. The \(dqref\(dq links in this
document link to the description of the individual constructs in the reST
reference.
.UNINDENT
.UNINDENT
.SS Paragraphs
.sp
The paragraph (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#paragraphs'\fI\%ref\fP\X'tty: link') is the most basic block in a reST
document. Paragraphs are simply chunks of text separated by one or more blank
lines. As in Python, indentation is significant in reST, so all lines of the
same paragraph must be left\-aligned to the same level of indentation.
.SS Inline markup
.sp
The standard reST inline markup is quite simple: use
.INDENT 0.0
.IP \(bu 2
one asterisk: \fB*text*\fP for emphasis (italics),
.IP \(bu 2
two asterisks: \fB**text**\fP for strong emphasis (boldface), and
.IP \(bu 2
backquotes: \fB\(ga\(gatext\(ga\(ga\fP for code samples.
.UNINDENT
.sp
If asterisks or backquotes appear in running text and could be confused with
inline markup delimiters, they have to be escaped with a backslash.
.sp
Be aware of some restrictions of this markup:
.INDENT 0.0
.IP \(bu 2
it may not be nested,
.IP \(bu 2
content may not start or end with whitespace: \fB* text*\fP is wrong,
.IP \(bu 2
it must be separated from surrounding text by non\-word characters. Use a
backslash escaped space to work around that: \fBthisis\e *one*\e word\fP\&.
.UNINDENT
.sp
These restrictions may be lifted in future versions of the docutils.
.sp
It is also possible to replace or expand upon some of this inline markup with
roles. Refer to \fI\%Roles\fP for more information.
.SS Lists and Quote\-like blocks
.sp
List markup (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#bullet-lists'\fI\%ref\fP\X'tty: link') is natural: just place an asterisk at
the start of a paragraph and indent properly. The same goes for numbered
lists; they can also be autonumbered using a \fB#\fP sign:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
* This is a bulleted list.
* It has two items, the second
item uses two lines.
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.
.EE
.UNINDENT
.UNINDENT
.sp
Nested lists are possible, but be aware that they must be separated from the
parent list items by blank lines:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list continues
.EE
.UNINDENT
.UNINDENT
.sp
Definition lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists'\fI\%ref\fP\X'tty: link') are created as follows:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
term (up to a line of text)
Definition of the term, which must be indented
and can even consist of multiple paragraphs
next term
Description.
.EE
.UNINDENT
.UNINDENT
.sp
Note that the term cannot have more than one line of text.
.sp
Quoted paragraphs (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#block-quotes'\fI\%ref\fP\X'tty: link') are created by just indenting
them more than the surrounding paragraphs.
.sp
Line blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks'\fI\%ref\fP\X'tty: link') are a way of preserving line breaks:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
| These lines are
| broken exactly like in
| the source file.
.EE
.UNINDENT
.UNINDENT
.sp
There are also several more special blocks available:
.INDENT 0.0
.IP \(bu 2
field lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists'\fI\%ref\fP\X'tty: link', with caveats noted in
\fI\%Field Lists\fP)
.IP \(bu 2
option lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists'\fI\%ref\fP\X'tty: link')
.IP \(bu 2
quoted literal blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#quoted-literal-blocks'\fI\%ref\fP\X'tty: link')
.IP \(bu 2
doctest blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks'\fI\%ref\fP\X'tty: link')
.UNINDENT
.SS Literal blocks
.sp
Literal code blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks'\fI\%ref\fP\X'tty: link') are introduced by ending a
paragraph with the special marker \fB::\fP\&. The literal block must be indented
(and, like all paragraphs, separated from the surrounding ones by blank
lines):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
This is a normal text paragraph. The next paragraph is a code sample::
It is not processed in any way, except
that the indentation is removed.
It can span multiple lines.
This is a normal text paragraph again.
.EE
.UNINDENT
.UNINDENT
.sp
The handling of the \fB::\fP marker is smart:
.INDENT 0.0
.IP \(bu 2
If it occurs as a paragraph of its own, that paragraph is completely left out
of the document.
.IP \(bu 2
If it is preceded by whitespace, the marker is removed.
.IP \(bu 2
If it is preceded by non\-whitespace, the marker is replaced by a single
colon.
.UNINDENT
.sp
That way, the second sentence in the above example\(aqs first paragraph would be
rendered as \(dqThe next paragraph is a code sample:\(dq.
.sp
Code highlighting can be enabled for these literal blocks on a document\-wide
basis using the \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' directive and on a project\-wide basis
using the \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' configuration option. The
\X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive can be used to set highlighting on a
block\-by\-block basis. These directives are discussed later.
.SS Doctest blocks
.sp
Doctest blocks (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks'\fI\%ref\fP\X'tty: link') are interactive Python sessions
cut\-and\-pasted into docstrings. They do not require the
\fI\%literal blocks\fP syntax. The doctest block must end
with a blank line and should \fInot\fP end with an unused prompt:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>>> 1 + 1
2
.EE
.UNINDENT
.UNINDENT
.SS Tables
.sp
For \fIgrid tables\fP (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables'\fI\%ref\fP\X'tty: link'), you have to \(dqpaint\(dq the cell
grid yourself. They look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
| body row 2 | ... | ... | |
+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+
.EE
.UNINDENT
.UNINDENT
.sp
\fISimple tables\fP (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables'\fI\%ref\fP\X'tty: link') are easier to write, but
limited: they must contain more than one row, and the first column cells cannot
contain multiple lines. They look like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
.EE
.UNINDENT
.UNINDENT
.sp
Two more syntaxes are supported: \fICSV tables\fP and \fIList tables\fP\&. They use an
\fIexplicit markup block\fP\&. Refer to \X'tty: link #table-directives'\fI\%Tables\fP\X'tty: link' for more information.
.SS Hyperlinks
.SS External links
.sp
Use \fB\(gaLink text \(ga_\fP for inline web links. If the
link text should be the web address, you don\(aqt need special markup at all, the
parser finds links and mail addresses in ordinary text.
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
There must be a space between the link text and the opening < for the URL.
.UNINDENT
.UNINDENT
.sp
You can also separate the link and the target definition (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets'\fI\%ref\fP\X'tty: link'), like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
This is a paragraph that contains \(gaa link\(ga_.
\&.. _a link: https://domain.invalid/
.EE
.UNINDENT
.UNINDENT
.SS Internal links
.sp
Internal linking is done via a special reST role provided by Sphinx, see the
section on specific markup, \X'tty: link #ref-role'\fI\%Cross\-referencing arbitrary locations\fP\X'tty: link'\&.
.SS Sections
.sp
Section headers (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections'\fI\%ref\fP\X'tty: link') are created by underlining (and
optionally overlining) the section title with a punctuation character, at least
as long as the text:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
=================
This is a heading
=================
.EE
.UNINDENT
.UNINDENT
.sp
Normally, there are no heading levels assigned to certain characters as the
structure is determined from the succession of headings. However, this
convention is used in \X'tty: link https://devguide.python.org/documentation/markup/#sections'\fI\%Python Developer\(aqs Guide for documenting\fP\X'tty: link' which you may
follow:
.INDENT 0.0
.IP \(bu 2
\fB#\fP with overline, for parts
.IP \(bu 2
\fB*\fP with overline, for chapters
.IP \(bu 2
\fB=\fP for sections
.IP \(bu 2
\fB\-\fP for subsections
.IP \(bu 2
\fB^\fP for subsubsections
.IP \(bu 2
\fB\(dq\fP for paragraphs
.UNINDENT
.sp
Of course, you are free to use your own marker characters (see the reST
documentation), and use a deeper nesting level, but keep in mind that most
target formats (HTML, LaTeX) have a limited supported nesting depth.
.SS Field Lists
.sp
Field lists (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists'\fI\%ref\fP\X'tty: link') are sequences of fields marked up like
this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
:fieldname: Field content
.EE
.UNINDENT
.UNINDENT
.sp
They are commonly used in Python documentation:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
def my_function(my_arg, my_other_arg):
\(dq\(dq\(dqA function just for me.
:param my_arg: The first of my arguments.
:param my_other_arg: The second of my arguments.
:returns: A message (just for me, of course).
\(dq\(dq\(dq
.EE
.UNINDENT
.UNINDENT
.sp
Sphinx extends standard docutils behavior and intercepts field lists specified
at the beginning of documents. Refer to \fI\%Field Lists\fP for more
information.
.SS Roles
.sp
A role or \(dqcustom interpreted text role\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html'\fI\%ref\fP\X'tty: link') is an inline
piece of explicit markup. It signifies that the enclosed text should be
interpreted in a specific way. Sphinx uses this to provide semantic markup and
cross\-referencing of identifiers, as described in the appropriate section. The
general syntax is \fB:rolename:\(gacontent\(ga\fP\&.
.sp
Docutils supports the following roles:
.INDENT 0.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis'\fI\%emphasis\fP\X'tty: link' \-\- equivalent of \fB*emphasis*\fP
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#strong'\fI\%strong\fP\X'tty: link' \-\- equivalent of \fB**strong**\fP
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal'\fI\%literal\fP\X'tty: link' \-\- equivalent of \fB\(ga\(galiteral\(ga\(ga\fP
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#subscript'\fI\%subscript\fP\X'tty: link' \-\- subscript text
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#superscript'\fI\%superscript\fP\X'tty: link' \-\- superscript text
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/roles.html#title-reference'\fI\%title\-reference\fP\X'tty: link' \-\- for titles of books, periodicals, and other
materials
.UNINDENT
.sp
Refer to \fI\%Roles\fP for roles added by Sphinx.
.SS Explicit Markup
.sp
\(dqExplicit markup\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#explicit-markup-blocks'\fI\%ref\fP\X'tty: link') is used in reST for
most constructs that need special handling, such as footnotes,
specially\-highlighted paragraphs, comments, and generic directives.
.sp
An explicit markup block begins with a line starting with \fB\&..\fP followed by
whitespace and is terminated by the next paragraph at the same level of
indentation. (There needs to be a blank line between explicit markup and
normal paragraphs. This may all sound a bit complicated, but it is intuitive
enough when you write it.)
.SS Directives
.sp
A directive (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives'\fI\%ref\fP\X'tty: link') is a generic block of explicit markup.
Along with roles, it is one of the extension mechanisms of reST, and Sphinx
makes heavy use of it.
.sp
Docutils supports the following directives:
.INDENT 0.0
.IP \(bu 2
Admonitions: \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#attention'\fI\%attention\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#caution'\fI\%caution\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#danger'\fI\%danger\fP\X'tty: link',
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#error'\fI\%error\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#hint'\fI\%hint\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#important'\fI\%important\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#note'\fI\%note\fP\X'tty: link',
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#tip'\fI\%tip\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#warning'\fI\%warning\fP\X'tty: link' and the generic
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions'\fI\%admonition\fP\X'tty: link'\&. (Most themes style only \(dqnote\(dq and
\(dqwarning\(dq specially.)
.IP \(bu 2
Images:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#image'\fI\%image\fP\X'tty: link' (see also \fI\%Images\fP below)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure'\fI\%figure\fP\X'tty: link' (an image with caption and optional legend)
.UNINDENT
.IP \(bu 2
Additional body elements:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents\fP\X'tty: link' (a local, i.e. for the current file
only, table of contents)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#container'\fI\%container\fP\X'tty: link' (a container with a custom class, useful to generate an
outer \fB
\fP in HTML)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric'\fI\%rubric\fP\X'tty: link' (a heading without relation to the document sectioning)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic'\fI\%topic\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#sidebar'\fI\%sidebar\fP\X'tty: link' (special highlighted body elements)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal'\fI\%parsed\-literal\fP\X'tty: link' (literal block that supports inline markup)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph'\fI\%epigraph\fP\X'tty: link' (a block quote with optional attribution line)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights'\fI\%highlights\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote'\fI\%pull\-quote\fP\X'tty: link' (block quotes with their own
class attribute)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#compound-paragraph'\fI\%compound\fP\X'tty: link' (a compound paragraph)
.UNINDENT
.IP \(bu 2
Special tables:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' (a table with title)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link' (a table generated from comma\-separated values)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link' (a table generated from a list of lists)
.UNINDENT
.IP \(bu 2
Special directives:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through'\fI\%raw\fP\X'tty: link' (include raw target\-format markup)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' (include reStructuredText from another file) \-\- in Sphinx,
when given an absolute include file path, this directive takes it as
relative to the source directory
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#class'\fI\%class\fP\X'tty: link' (assign a class attribute to the next element)
.sp
\fBNOTE:\fP
.INDENT 2.0
.INDENT 3.5
When the default domain contains a \fBclass\fP directive, this directive
will be shadowed. Therefore, Sphinx re\-exports it as \fBrst\-class\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.IP \(bu 2
HTML specifics:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link'
(generation of HTML \fB\fP tags, see also \fI\%HTML Metadata\fP below)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata-document-title'\fI\%title\fP\X'tty: link' (override document title)
.UNINDENT
.IP \(bu 2
Influencing markup:
.INDENT 2.0
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#default-role'\fI\%default\-role\fP\X'tty: link' (set a new default role)
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#role'\fI\%role\fP\X'tty: link' (create a new role)
.UNINDENT
.sp
Since these are only per\-file, better use Sphinx\(aqs facilities for setting the
\X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link'\&.
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Do \fInot\fP use the directives \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#sectnum'\fI\%sectnum\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#header'\fI\%header\fP\X'tty: link' and
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#footer'\fI\%footer\fP\X'tty: link'\&.
.UNINDENT
.UNINDENT
.sp
Directives added by Sphinx are described in \fI\%Directives\fP\&.
.sp
Basically, a directive consists of a name, arguments, options and content.
(Keep this terminology in mind, it is used in the next chapter describing
custom directives.) Looking at this example,
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. function:: foo(x)
foo(y, z)
:module: some.module.name
Return a line of text input from the user.
.EE
.UNINDENT
.UNINDENT
.sp
\fBfunction\fP 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
\fBmodule\fP (as you can see, options are given in the lines immediately
following the arguments and indicated by the colons). Options must be indented
to the same level as the directive content.
.sp
The directive content follows after a blank line and is indented relative to
the directive start or if options are present, by the same amount as the
options.
.sp
Be careful as the indent is not a fixed number of whitespace, e.g. three, but
any number whitespace. This can be surprising when a fixed indent is used
throughout the document and can make a difference for directives which are
sensitive to whitespace. Compare:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. code\-block::
:caption: A cool example
The output of this line starts with four spaces.
\&.. code\-block::
The output of this line has no spaces at the beginning.
.EE
.UNINDENT
.UNINDENT
.sp
In the first code block, the indent for the content was fixated by the option
line to three spaces, consequently the content starts with four spaces.
In the latter the indent was fixed by the content itself to seven spaces, thus
it does not start with a space.
.SS Images
.sp
reST supports an image directive (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#image'\fI\%ref\fP\X'tty: link'), used like so:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. image:: gnu.png
(options)
.EE
.UNINDENT
.UNINDENT
.sp
When used within Sphinx, the file name given (here \fBgnu.png\fP) must either be
relative to the source file, or absolute which means that they are relative to
the top source directory. For example, the file \fBsketch/spam.rst\fP could
refer to the image \fBimages/spam.png\fP as \fB\&../images/spam.png\fP or
\fB/images/spam.png\fP\&.
.sp
Sphinx will automatically copy image files over to a subdirectory of the output
directory on building (e.g. the \fB_static\fP directory for HTML output.)
.sp
Interpretation of image size options (\fBwidth\fP and \fBheight\fP) is as follows:
if the size has no unit or the unit is pixels, the given size will only be
respected for output channels that support pixels. Other units (like \fBpt\fP for
points) will be used for HTML and LaTeX output (the latter replaces \fBpt\fP by
\fBbp\fP as this is the TeX unit such that \fB72bp=1in\fP).
.sp
Sphinx extends the standard docutils behavior by allowing an asterisk for the
extension:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. image:: gnu.*
.EE
.UNINDENT
.UNINDENT
.sp
Sphinx then searches for all images matching the provided pattern and
determines their type. Each builder then chooses the best image out of these
candidates. For instance, if the file name \fBgnu.*\fP was given and two files
\fBgnu.pdf\fP and \fBgnu.png\fP existed in the source tree, the LaTeX
builder would choose the former, while the HTML builder would prefer the
latter. Supported image types and choosing priority are defined at
\fI\%Builders\fP\&.
.sp
Note that image file names should not contain spaces.
.sp
Changed in version 0.4: Added the support for file names ending in an asterisk.
.sp
Changed in version 0.6: Image paths can now be absolute.
.sp
Changed in version 1.5: latex target supports pixels (default is \fB96px=1in\fP).
.SS Footnotes
.sp
For footnotes (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes'\fI\%ref\fP\X'tty: link'), use \fB[#name]_\fP to mark the footnote
location, and add the footnote body at the bottom of the document after a
\(dqFootnotes\(dq rubric heading, like so:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
\&.. rubric:: Footnotes
\&.. [#f1] Text of the first footnote.
\&.. [#f2] Text of the second footnote.
.EE
.UNINDENT
.UNINDENT
.sp
You can also explicitly number the footnotes (\fB[1]_\fP) or use auto\-numbered
footnotes without names (\fB[#]_\fP).
.SS Citations
.sp
Standard reST citations (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#citations'\fI\%ref\fP\X'tty: link') are supported, with the
additional feature that they are \(dqglobal\(dq, i.e. all citations can be referenced
from all files. Use them like so:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Lorem ipsum [Ref]_ dolor sit amet.
\&.. [Ref] Book or article reference, URL or whatever.
.EE
.UNINDENT
.UNINDENT
.sp
Citation usage is similar to footnote usage, but with a label that is not
numeric or begins with \fB#\fP\&.
.SS Substitutions
.sp
reST supports \(dqsubstitutions\(dq (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%ref\fP\X'tty: link'), which
are pieces of text and/or markup referred to in the text by \fB|name|\fP\&. They
are defined like footnotes with explicit markup blocks, like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. |name| replace:: replacement *text*
.EE
.UNINDENT
.UNINDENT
.sp
or this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. |caution| image:: warning.png
:alt: Warning!
.EE
.UNINDENT
.UNINDENT
.sp
See the \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%reST reference for substitutions\fP\X'tty: link'
for details.
.sp
If you want to use some substitutions for all documents, put them into
\X'tty: link #confval-rst_prolog'\fI\%rst_prolog\fP\X'tty: link' or \X'tty: link #confval-rst_epilog'\fI\%rst_epilog\fP\X'tty: link' or put them into a separate file
and include it into all documents you want to use them in, using the
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive. (Be sure to give the include file a file name
extension differing from that of other source files, to avoid Sphinx finding it
as a standalone document.)
.sp
Sphinx defines some default substitutions, see \X'tty: link #default-substitutions'\fI\%Substitutions\fP\X'tty: link'\&.
.SS Comments
.sp
Every explicit markup block which isn\(aqt a valid markup construct (like the
footnotes above) is regarded as a comment (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments'\fI\%ref\fP\X'tty: link'). For
example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. This is a comment.
.EE
.UNINDENT
.UNINDENT
.sp
You can indent text after a comment start to form multiline comments:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&..
This whole indented block
is a comment.
Still in the comment.
.EE
.UNINDENT
.UNINDENT
.SS HTML Metadata
.sp
The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta'\fI\%meta\fP\X'tty: link' directive allows specifying the HTML
\X'tty: link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta'\fI\%metadata element\fP\X'tty: link' of a Sphinx documentation page. For example, the
directive:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. meta::
:description: The Sphinx documentation builder
:keywords: Sphinx, documentation, builder
.EE
.UNINDENT
.UNINDENT
.sp
will generate the following HTML output:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
.EE
.UNINDENT
.UNINDENT
.sp
Also, Sphinx will add the keywords as specified in the meta directive to the
search index. Thereby, the \fBlang\fP attribute of the meta element is
considered. For example, the directive:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. meta::
:keywords: backup
:keywords lang=en: pleasefindthiskey pleasefindthiskeytoo
:keywords lang=de: bittediesenkeyfinden
.EE
.UNINDENT
.UNINDENT
.sp
adds the following words to the search indices of builds with different language
configurations:
.INDENT 0.0
.IP \(bu 2
\fBpleasefindthiskey\fP, \fBpleasefindthiskeytoo\fP to \fIEnglish\fP builds;
.IP \(bu 2
\fBbittediesenkeyfinden\fP to \fIGerman\fP builds;
.IP \(bu 2
\fBbackup\fP to builds in all languages.
.UNINDENT
.SS Source encoding
.sp
Since the easiest way to include special characters like em dashes or copyright
signs in reST is to directly write them as Unicode characters, one has to
specify an encoding. Sphinx assumes source files to be encoded in UTF\-8 by
default; you can change this with the \X'tty: link #confval-source_encoding'\fI\%source_encoding\fP\X'tty: link' config value.
.SS Gotchas
.sp
There are some problems one commonly runs into while authoring reST documents:
.INDENT 0.0
.IP \(bu 2
\fBSeparation of inline markup:\fP As said above, inline markup spans must be
separated from the surrounding text by non\-word characters, you have to use a
backslash\-escaped space to get around that. See \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions'\fI\%the reference\fP\X'tty: link' for the details.
.IP \(bu 2
\fBNo nested inline markup:\fP Something like \fB*see :func:\(gafoo\(ga*\fP is not
possible.
.UNINDENT
.SS Roles
.sp
Sphinx uses interpreted text roles to insert semantic markup into documents.
They are written as \fB:rolename:\(gacontent\(ga\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The default role (\fB\(gacontent\(ga\fP) has no special meaning by default. You are
free to use it for anything you like, e.g. variable names; use the
\X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link' config value to set it to a known role \-\- the
\X'tty: link #role-any'\fI\%any\fP\X'tty: link' role to find anything or the \X'tty: link #role-py-obj'\fI\%py:obj\fP\X'tty: link' role to find
Python objects are very useful for this.
.UNINDENT
.UNINDENT
.sp
See \fI\%Domains\fP for roles added by domains.
.SS Cross\-referencing syntax
.sp
See \fI\%Cross\-referencing syntax\fP\&.
.sp
Cross\-reference roles include:
.INDENT 0.0
.IP \(bu 2
\X'tty: link #role-any'\fI\%any\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-doc'\fI\%doc\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-download'\fI\%download\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-envvar'\fI\%envvar\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-keyword'\fI\%keyword\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-numref'\fI\%numref\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-option'\fI\%option\fP\X'tty: link' (and the deprecated \fBcmdoption\fP)
.IP \(bu 2
\X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-term'\fI\%term\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #role-token'\fI\%token\fP\X'tty: link'
.UNINDENT
.SS Inline code highlighting
.INDENT 0.0
.TP
.B :code:
An \fIinline\fP code example. When used directly, this role just displays the
text \fIwithout\fP syntax highlighting, as a literal.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
By default, inline code such as :code:\(ga1 + 2\(ga just displays without
highlighting.
.EE
.UNINDENT
.UNINDENT
.sp
Displays: By default, inline code such as \fB1 + 2\fP just displays without
highlighting.
.sp
Unlike the \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive, this role does not respect the
default language set by the \X'tty: link #directive-highlight'\fI\%highlight\fP\X'tty: link' directive.
.sp
To enable syntax highlighting, you must first use the Docutils \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#role'\fI\%role\fP\X'tty: link'
directive to define a custom role associated with a specific language:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. role:: python(code)
:language: python
In Python, :python:\(ga1 + 2\(ga is equal to :python:\(ga3\(ga.
.EE
.UNINDENT
.UNINDENT
.sp
To display a multi\-line code example, use the \X'tty: link #directive-code-block'\fI\%code\-block\fP\X'tty: link' directive
instead.
.UNINDENT
.SS Math
.INDENT 0.0
.TP
.B :math:
Role for inline math. Use like this:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
Since Pythagoras, we know that :math:\(gaa^2 + b^2 = c^2\(ga.
.EE
.UNINDENT
.UNINDENT
.sp
Displays: Since Pythagoras, we know that a^2 + b^2 = c^2\&.
.UNINDENT
.INDENT 0.0
.TP
.B :eq:
Same as \X'tty: link #role-math-numref'\fI\%math:numref\fP\X'tty: link'\&.
.UNINDENT
.SS Other semantic markup
.sp
The following roles don\(aqt do anything special except formatting the text in a
different style:
.INDENT 0.0
.TP
.B :abbr:
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, and
output only once in LaTeX.
.sp
For example: \fB:abbr:\(gaLIFO (last\-in, first\-out)\(ga\fP displays
LIFO\&.
.sp
Added in version 0.6.
.UNINDENT
.INDENT 0.0
.TP
.B :command:
The name of an OS\-level command, such as \fBrm\fP\&.
.sp
For example: \fBrm\fP
.UNINDENT
.INDENT 0.0
.TP
.B :dfn:
Mark the defining instance of a term in the text. (No index entries are
generated.)
.sp
For example: \fIbinary mode\fP
.UNINDENT
.INDENT 0.0
.TP
.B :file:
The name of a file or directory. Within the contents, you can use curly
braces to indicate a \(dqvariable\(dq part, for example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&... is installed in :file:\(ga/usr/lib/python3.{x}/site\-packages\(ga ...
.EE
.UNINDENT
.UNINDENT
.sp
Displays: ... is installed in \fB/usr/lib/python3.\fP\fIx\fP\fB/site\-packages\fP ...
.sp
In the built documentation, the \fBx\fP will be displayed differently to
indicate that it is to be replaced by the Python minor version.
.UNINDENT
.INDENT 0.0
.TP
.B :guilabel:
Labels presented as part of an interactive user interface should be marked
using \fBguilabel\fP\&. This includes labels from text\-based interfaces such as
those created using \X'tty: link https://docs.python.org/3/library/curses.html#module-curses'\fI\%curses\fP\X'tty: link' or other text\-based libraries. Any label
used in the interface should be marked with this role, including button
labels, window titles, field names, menu and menu selection names, and even
values in selection lists.
.sp
Changed in version 1.0: An accelerator key for the GUI label can be included using an ampersand;
this will be stripped and displayed underlined in the output (for example:
\fB:guilabel:\(ga&Cancel\(ga\fP displays Cancel). To include a literal
ampersand, double it.
.UNINDENT
.INDENT 0.0
.TP
.B :kbd:
Mark a sequence of keystrokes. What form the key sequence takes may depend
on platform\- or application\-specific conventions. When there are no
relevant conventions, the names of modifier keys should be spelled out, to
improve accessibility for new users and non\-native speakers. For example,
an \fIxemacs\fP key sequence may be marked like \fB:kbd:\(gaC\-x C\-f\(ga\fP, but without
reference to a specific application or platform, the same sequence should be
marked as \fB:kbd:\(gaControl\-x Control\-f\(ga\fP, displaying \fBC\-x C\-f\fP and
\fBControl\-x Control\-f\fP respectively.
.UNINDENT
.INDENT 0.0
.TP
.B :mailheader:
The name of an RFC 822\-style mail header. This markup does not imply that
the header is being used in an email message, but can be used to refer to
any header of the same \(dqstyle.\(dq This is also used for headers defined by
the various MIME specifications. The header name should be entered in the
same way it would normally be found in practice, with the camel\-casing
conventions being preferred where there is more than one common usage. For
example: \fB:mailheader:\(gaContent\-Type\(ga\fP displays \fIContent\-Type\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B :makevar:
The name of a \fBmake\fP variable.
.sp
For example: \fBhelp\fP
.UNINDENT
.INDENT 0.0
.TP
.B :manpage:
A reference to a Unix manual page including the section, e.g.
\fB:manpage:\(gals(1)\(ga\fP displays \fBls(1)\fP\&. Creates a hyperlink to an
external site rendering the manpage if \X'tty: link #confval-manpages_url'\fI\%manpages_url\fP\X'tty: link' is defined.
.sp
Changed in version 7.3: Allow specifying a target with \fB<>\fP, like hyperlinks.
For example, \fB:manpage:\(gablah \(ga\fP displays \fBblah\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B :menuselection:
Menu selections should be marked using the \fBmenuselection\fP role. This is
used to mark a complete sequence of menu selections, including selecting
submenus and choosing a specific operation, or any subsequence of such a
sequence. The names of individual selections should be separated by
\fB\-\->\fP\&.
.sp
For example, to mark the selection \(dqStart > Programs\(dq, use this markup:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
:menuselection:\(gaStart \-\-> Programs\(ga
.EE
.UNINDENT
.UNINDENT
.sp
Displays: Start ‣ Programs
.sp
When including a selection that includes some trailing indicator, such as
the ellipsis some operating systems use to indicate that the command opens a
dialog, the indicator should be omitted from the selection name.
.sp
\fBmenuselection\fP also supports ampersand accelerators just like
\fI\%guilabel\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B :mimetype:
The name of a MIME type, or a component of a MIME type (the major or minor
portion, taken alone).
.sp
For example: \fItext/plain\fP
.UNINDENT
.INDENT 0.0
.TP
.B :newsgroup:
The name of a Usenet newsgroup.
.sp
For example: \fIcomp.lang.python\fP
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.SS Todo
.sp
Is this not part of the standard domain?
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B :program:
The name of an executable program. This may differ from the file name for
the executable for some platforms. In particular, the \fB\&.exe\fP (or other)
extension should be omitted for Windows programs.
.sp
For example: \fBcurl\fP
.UNINDENT
.INDENT 0.0
.TP
.B :regexp:
A regular expression. Quotes should not be included.
.sp
For example: \fB([abc])+\fP
.UNINDENT
.INDENT 0.0
.TP
.B :samp:
A piece of literal text, such as code. Within the contents, you can use
curly braces to indicate a \(dqvariable\(dq part, as in \fI\%file\fP\&. For
example, in \fB:samp:\(gaprint(1+{variable})\(ga\fP, the part \fBvariable\fP would be
emphasized: \fBprint(1+\fP\fIvariable\fP\fB)\fP
.sp
If you don\(aqt need the \(dqvariable part\(dq indication, use the standard
\fI\%code\fP role instead.
.sp
Changed in version 1.8: Allowed to escape curly braces with double backslash. For example, in
\fB:samp:\(gaprint(f\(dqanswer=\e\e{1+{variable}*2\e\e}\(dq)\(ga\fP, the part \fBvariable\fP
would be emphasized and the escaped curly braces would be displayed:
\fBprint(f\(dqanswer={1+\fP\fIvariable\fP\fB*2}\(dq)\fP
.UNINDENT
.sp
There is also an \X'tty: link #role-index'\fI\%index\fP\X'tty: link' role to generate index entries.
.sp
The following roles generate external links:
.INDENT 0.0
.TP
.B :pep:
A reference to a Python Enhancement Proposal. This generates appropriate
index entries. The text \(dqPEP \fInumber\fP\(dq is generated; in the HTML output,
this text is a hyperlink to an online copy of the specified PEP. You can
link to a specific section by saying \fB:pep:\(ganumber#anchor\(ga\fP\&.
.sp
For example: \X'tty: link https://peps.python.org/pep-0008/'\fI\%PEP 8\fP\X'tty: link'
.UNINDENT
.INDENT 0.0
.TP
.B :rfc:
A reference to an Internet Request for Comments. This generates appropriate
index entries. The text \(dqRFC \fInumber\fP\(dq is generated; in the HTML output,
this text is a hyperlink to an online copy of the specified RFC. You can
link to a specific section by saying \fB:rfc:\(ganumber#anchor\(ga\fP\&.
.sp
For example: \X'tty: link https://datatracker.ietf.org/doc/html/rfc2324.html'\fI\%RFC 2324\fP\X'tty: link'
.UNINDENT
.sp
Note that there are no special roles for including hyperlinks as you can use
the standard reST markup for that purpose.
.SS Substitutions
.sp
The documentation system provides some substitutions that are defined by
default. They are set in the build configuration file.
.INDENT 0.0
.TP
.B |release|
Replaced by the project release the documentation refers to. This is meant
to be the full version string including alpha/beta/release candidate tags,
e.g. \fB2.5.2b3\fP\&. Set by \X'tty: link #confval-release'\fI\%release\fP\X'tty: link'\&.
.UNINDENT
.INDENT 0.0
.TP
.B |version|
Replaced by the project version the documentation refers to. This is meant to
consist only of the major and minor version parts, e.g. \fB2.5\fP, even for
version 2.5.1. Set by \X'tty: link #confval-version'\fI\%version\fP\X'tty: link'\&.
.UNINDENT
.INDENT 0.0
.TP
.B |today|
Replaced by either today\(aqs date (the date on which the document is read), or
the date set in the build configuration file. Normally has the format
\fBApril 14, 2007\fP\&. Set by \X'tty: link #confval-today_fmt'\fI\%today_fmt\fP\X'tty: link' and \X'tty: link #confval-today'\fI\%today\fP\X'tty: link'\&.
.UNINDENT
.INDENT 0.0
.TP
.B |translation progress|
Replaced by the translation progress of the document.
This substitution is intended for use by document translators
as a marker for the translation progress of the document.
.UNINDENT
.SS Directives
.sp
\X'tty: link #rst-directives'\fI\%As previously discussed\fP\X'tty: link', a directive is a generic block
of explicit markup. While Docutils provides a number of directives, Sphinx
provides many more and uses directives as one of the primary extension
mechanisms.
.sp
See \fI\%Domains\fP for roles added by domains.
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
Refer to the \X'tty: link #rst-directives'\fI\%reStructuredText Primer\fP\X'tty: link' for an overview
of the directives provided by Docutils.
.UNINDENT
.UNINDENT
.SS Table of contents
.sp
Since reST does not have facilities to interconnect several documents, or split
documents into multiple output files, Sphinx uses a custom directive to add
relations between the single files the documentation is made of, as well as
tables of contents. The \fBtoctree\fP directive is the central element.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Simple \(dqinclusion\(dq of one file in another can be done with the
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#include'\fI\%include\fP\X'tty: link' directive.
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
To create table of contents for current document (.rst file), use the
standard reST \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents'\fI\%contents directive\fP\X'tty: link'\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. toctree::
This directive inserts a \(dqTOC tree\(dq at the current location, using the
individual TOCs (including \(dqsub\-TOC trees\(dq) of the documents given in the
directive body. Relative document names (not beginning with a slash) are
relative to the document the directive occurs in, absolute names are relative
to the source directory. A numeric \fBmaxdepth\fP option may be given to
indicate the depth of the tree; by default, all levels are included. [1]
.sp
The representation of \(dqTOC tree\(dq is changed in each output format. The
builders that output multiple files (ex. HTML) treat it as a collection of
hyperlinks. On the other hand, the builders that output a single file (ex.
LaTeX, man page, etc.) replace it with the content of the documents on the
TOC tree.
.sp
Consider this example (taken from the Python docs\(aq library reference index):
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:maxdepth: 2
intro
strings
datatypes
numeric
(many more documents listed here)
.EE
.UNINDENT
.UNINDENT
.sp
This accomplishes two things:
.INDENT 7.0
.IP \(bu 2
Tables of contents from all those documents are inserted, with a maximum
depth of two, that means one nested heading. \fBtoctree\fP directives in
those documents are also taken into account.
.IP \(bu 2
Sphinx knows the relative order of the documents \fBintro\fP,
\fBstrings\fP and so forth, and it knows that they are children of the shown
document, the library index. From this information it generates \(dqnext
chapter\(dq, \(dqprevious chapter\(dq and \(dqparent chapter\(dq links.
.UNINDENT
.sp
\fBEntries\fP
.sp
Document titles in the \fI\%toctree\fP will be automatically read from the
title of the referenced document. If that isn\(aqt what you want, you can
specify an explicit title and target using a similar syntax to reST
hyperlinks (and Sphinx\(aqs \X'tty: link #xref-syntax'\fI\%cross\-referencing syntax\fP\X'tty: link'). This
looks like:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
intro
All about strings
datatypes
.EE
.UNINDENT
.UNINDENT
.sp
The second line above will link to the \fBstrings\fP document, but will use the
title \(dqAll about strings\(dq instead of the title of the \fBstrings\fP document.
.sp
You can also add external links, by giving an HTTP URL instead of a document
name.
.sp
\fBSection numbering\fP
.sp
If you want to have section numbers even in HTML output, give the
\fBtoplevel\fP toctree a \fBnumbered\fP option. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:numbered:
foo
bar
.EE
.UNINDENT
.UNINDENT
.sp
Numbering then starts at the heading of \fBfoo\fP\&. Sub\-toctrees are
automatically numbered (don\(aqt give the \fBnumbered\fP flag to those).
.sp
Numbering up to a specific depth is also possible, by giving the depth as a
numeric argument to \fBnumbered\fP\&.
.sp
\fBAdditional options\fP
.sp
You can use the \fBcaption\fP option to provide a toctree caption and you can
use the \fBname\fP option to provide an implicit target name that can be
referenced by using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link':
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:caption: Table of Contents
:name: mastertoc
foo
.EE
.UNINDENT
.UNINDENT
.sp
If you want only the titles of documents in the tree to show up, not other
headings of the same level, you can use the \fBtitlesonly\fP option:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:titlesonly:
foo
bar
.EE
.UNINDENT
.UNINDENT
.sp
You can use \(dqglobbing\(dq in toctree directives, by giving the \fBglob\fP flag
option. All entries are then matched against the list of available
documents, and matches are inserted into the list alphabetically. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:glob:
intro*
recipe/*
*
.EE
.UNINDENT
.UNINDENT
.sp
This includes first all documents whose names start with \fBintro\fP, then all
documents in the \fBrecipe\fP folder, then all remaining documents (except the
one containing the directive, of course.) [2]
.sp
The special entry name \fBself\fP stands for the document containing the
toctree directive. This is useful if you want to generate a \(dqsitemap\(dq from
the toctree.
.sp
You can use the \fBreversed\fP flag option to reverse the order of the entries
in the list. This can be useful when using the \fBglob\fP flag option to
reverse the ordering of the files. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:glob:
:reversed:
recipe/*
.EE
.UNINDENT
.UNINDENT
.sp
You can also give a \(dqhidden\(dq option to the directive, like this:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:hidden:
doc_1
doc_2
.EE
.UNINDENT
.UNINDENT
.sp
This will still notify Sphinx of the document hierarchy, but not insert links
into the document at the location of the directive \-\- this makes sense if you
intend to insert these links yourself, in a different style, or in the HTML
sidebar.
.sp
In cases where you want to have only one top\-level toctree and hide all other
lower level toctrees you can add the \(dqincludehidden\(dq option to the top\-level
toctree entry:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. toctree::
:includehidden:
doc_1
doc_2
.EE
.UNINDENT
.UNINDENT
.sp
All other toctree entries can then be eliminated by the \(dqhidden\(dq option.
.sp
In the end, all documents in the \X'tty: link #term-source-directory'\fI\%source directory\fP\X'tty: link' (or subdirectories)
must occur in some \fBtoctree\fP directive; Sphinx will emit a warning if it
finds a file that is not included, because that means that this file will not
be reachable through standard navigation.
.sp
Use \X'tty: link #confval-exclude_patterns'\fI\%exclude_patterns\fP\X'tty: link' to explicitly exclude documents or
directories from building completely. Use \X'tty: link #metadata'\fI\%the \(dqorphan\(dq metadata\fP\X'tty: link' to let a document be built, but notify Sphinx that it is not
reachable via a toctree.
.sp
The \(dqroot document\(dq (selected by \X'tty: link #confval-root_doc'\fI\%root_doc\fP\X'tty: link') is the \(dqroot\(dq of the TOC
tree hierarchy. It can be used as the documentation\(aqs main page, or as a
\(dqfull table of contents\(dq if you don\(aqt give a \fBmaxdepth\fP option.
.sp
Changed in version 0.3: Added \(dqglobbing\(dq option.
.sp
Changed in version 0.6: Added \(dqnumbered\(dq and \(dqhidden\(dq options as well as external links and
support for \(dqself\(dq references.
.sp
Changed in version 1.0: Added \(dqtitlesonly\(dq option.
.sp
Changed in version 1.1: Added numeric argument to \(dqnumbered\(dq.
.sp
Changed in version 1.2: Added \(dqincludehidden\(dq option.
.sp
Changed in version 1.3: Added \(dqcaption\(dq and \(dqname\(dq option.
.UNINDENT
.SS Special names
.sp
Sphinx reserves some document names for its own use; you should not try to
create documents with these names \-\- it will cause problems.
.sp
The special document names (and pages generated for them) are:
.INDENT 0.0
.IP \(bu 2
\fBgenindex\fP, \fBmodindex\fP, \fBsearch\fP
.sp
These are used for the general index, the Python module index, and the search
page, respectively.
.sp
The general index is populated with entries from modules, all
index\-generating \X'tty: link #basic-domain-markup'\fI\%object descriptions\fP\X'tty: link', and from
\fI\%index\fP directives.
.sp
The Python module index contains one entry per \X'tty: link #directive-py-module'\fI\%py:module\fP\X'tty: link'
directive.
.sp
The search page contains a form that uses the generated JSON search index and
JavaScript to full\-text search the generated documents for search words; it
should work on every major browser that supports modern JavaScript.
.IP \(bu 2
every name beginning with \fB_\fP
.sp
Though few such names are currently used by Sphinx, you should not
create documents or document\-containing directories with such names. (Using
\fB_\fP as a prefix for a custom template directory is fine.)
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Be careful with unusual characters in filenames. Some formats may interpret
these characters in unexpected ways:
.INDENT 0.0
.IP \(bu 2
Do not use the colon \fB:\fP for HTML based formats. Links to other parts
may not work.
.IP \(bu 2
Do not use the plus \fB+\fP for the ePub format. Some resources may not be
found.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Paragraph\-level markup
.sp
These directives create short paragraphs and can be used inside information
units as well as normal text.
.INDENT 0.0
.TP
.B \&.. note::
An especially important bit of information about an API that a user should be
aware of when using whatever bit of API the note pertains to. The content of
the directive should be written in complete sentences and include all
appropriate punctuation.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. note::
This function is not suitable for sending spam e\-mails.
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. warning::
An important bit of information about an API that a user should be very aware
of when using whatever bit of API the warning pertains to. The content of
the directive should be written in complete sentences and include all
appropriate punctuation. This differs from \fI\%note\fP in that it is
recommended over \fI\%note\fP for information regarding security.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. versionadded:: version
This directive documents the version of the project which added the described
feature to the library or C API. When this applies to an entire module, it
should be placed at the top of the module section before any prose.
.sp
The first argument must be given and is the version in question; you can add
a second argument consisting of a \fIbrief\fP explanation of the change.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. versionadded:: 2.5
The *spam* parameter.
.EE
.UNINDENT
.UNINDENT
.sp
Note that there must be no blank line between the directive head and the
explanation; this is to make these blocks visually continuous in the markup.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. versionchanged:: version
Similar to \fI\%versionadded\fP, but describes when and what changed in
the named feature in some way (new parameters, changed side effects, etc.).
.UNINDENT
.INDENT 0.0
.TP
.B \&.. deprecated:: version
Similar to \fI\%versionchanged\fP, but describes when the feature was
deprecated. An explanation can also be given, for example to inform the
reader what should be used instead. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. deprecated:: 3.1
Use :func:\(gaspam\(ga instead.
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. versionremoved:: version
Similar to \fI\%versionadded\fP, but describes when the feature was removed.
An explanation may be provided to inform the reader what to use instead,
or why the feature was removed.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. versionremoved:: 4.0
The :func:\(gaspam\(ga function is more flexible, and should be used instead.
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 7.3.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. seealso::
Many sections include a list of references to module documentation or
external documents. These lists are created using the \fI\%seealso\fP
directive.
.sp
The \fI\%seealso\fP directive is typically placed in a section just before
any subsections. For the HTML output, it is shown boxed off from the main
flow of the text.
.sp
The content of the \fI\%seealso\fP directive should be a reST definition
list. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. seealso::
Module :py:mod:\(gazipfile\(ga
Documentation of the :py:mod:\(gazipfile\(ga standard module.
\(gaGNU tar manual, Basic Tar Format \(ga_
Documentation for tar archive files, including GNU tar extensions.
.EE
.UNINDENT
.UNINDENT
.sp
There\(aqs also a \(dqshort form\(dq allowed that looks like this:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. seealso:: modules :py:mod:\(gazipfile\(ga, :py:mod:\(gatarfile\(ga
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 0.5: The short form.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. rubric:: title
This directive creates a paragraph heading that is not used to create a
table of contents node.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If the \fItitle\fP of the rubric is \(dqFootnotes\(dq (or the selected language\(aqs
equivalent), this rubric is ignored by the LaTeX writer, since it is
assumed to only contain footnote definitions and therefore would create an
empty heading.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. centered::
This directive creates a centered boldfaced line of text. Use it as
follows:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. centered:: LICENSE AGREEMENT
.EE
.UNINDENT
.UNINDENT
.sp
Deprecated since version 1.1: This presentation\-only directive is a legacy from older versions.
Use a \X'tty: link #rstclass'\fI\%rst\-class\fP\X'tty: link' directive instead and add an
appropriate style.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. hlist::
This directive must contain a bullet list. It will transform it into a more
compact list by either distributing more than one item horizontally, or
reducing spacing between items, depending on the builder.
.sp
For builders that support the horizontal distribution, there is a \fBcolumns\fP
option that specifies the number of columns; it defaults to 2. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. hlist::
:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 0.6.
.UNINDENT
.SS Showing code examples
.sp
There are multiple ways to show syntax\-highlighted literal code blocks in
Sphinx:
.INDENT 0.0
.IP \(bu 2
using \X'tty: link #rst-doctest-blocks'\fI\%reST doctest blocks\fP\X'tty: link';
.IP \(bu 2
using \X'tty: link #rst-literal-blocks'\fI\%reST literal blocks\fP\X'tty: link', optionally in
combination with the \fI\%highlight\fP directive;
.IP \(bu 2
using the \fI\%code\-block\fP directive;
.IP \(bu 2
and using the \fI\%literalinclude\fP directive.
.UNINDENT
.sp
Doctest blocks can only be used
to show interactive Python sessions, while the remaining three can be used for
other languages. Of these three, literal blocks are useful when an entire
document, or at least large sections of it, use code blocks with the same
syntax and which should be styled in the same manner. On the other hand, the
\fI\%code\-block\fP directive makes more sense when you want more fine\-tuned
control over the styling of each block or when you have a document containing
code blocks using multiple varied syntaxes. Finally, the
\fI\%literalinclude\fP directive is useful for including entire code files
in your documentation.
.sp
In all cases, Syntax highlighting is provided by \X'tty: link https://pygments.org'\fI\%Pygments\fP\X'tty: link'\&. When using literal blocks, this is configured using
any \fI\%highlight\fP directives in the source file. When a \fBhighlight\fP
directive is encountered, it is used until the next \fBhighlight\fP directive is
encountered. If there is no \fBhighlight\fP directive in the file, the global
highlighting language is used. This defaults to \fBpython\fP but can be
configured using the \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' config value. The following
values are supported:
.INDENT 0.0
.IP \(bu 2
\fBnone\fP (no highlighting)
.IP \(bu 2
\fBdefault\fP (similar to \fBpython3\fP but with a fallback to \fBnone\fP without
warning highlighting fails; the default when \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link'
isn\(aqt set)
.IP \(bu 2
\fBguess\fP (let Pygments guess the lexer based on contents, only works with
certain well\-recognizable languages)
.IP \(bu 2
\fBpython\fP
.IP \(bu 2
\fBrest\fP
.IP \(bu 2
\fBc\fP
.IP \(bu 2
\&... and any other \X'tty: link https://pygments.org/docs/lexers'\fI\%lexer alias that Pygments supports\fP\X'tty: link'
.UNINDENT
.sp
If highlighting with the selected language fails (i.e. Pygments emits an
\(dqError\(dq token), the block is not highlighted in any way.
.sp
\fBIMPORTANT:\fP
.INDENT 0.0
.INDENT 3.5
The list of lexer aliases supported is tied to the Pygment version. If you
want to ensure consistent highlighting, you should fix your version of
Pygments.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. highlight:: language
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. highlight:: c
.EE
.UNINDENT
.UNINDENT
.sp
This language is used until the next \fBhighlight\fP directive is encountered.
As discussed previously, \fIlanguage\fP can be any lexer alias supported by
Pygments.
.sp
options
.INDENT 7.0
.TP
.B :linenothreshold: threshold (number (optional))
Enable to generate line numbers for code blocks.
.sp
This option takes an optional number as threshold parameter. If any
threshold given, the directive will produce line numbers only for the code
blocks longer than N lines. If not given, line numbers will be produced
for all of code blocks.
.sp
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. highlight:: python
:linenothreshold: 5
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B :force: (no value)
If given, minor errors on highlighting are ignored.
.sp
Added in version 2.1.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. code\-block:: [language]
.TP
.B \&.. sourcecode:: [language]
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: ruby
Some Ruby code.
.EE
.UNINDENT
.UNINDENT
.sp
The directive\(aqs alias name \fI\%sourcecode\fP works as well. This
directive takes a language name as an argument. It can be \X'tty: link https://pygments.org/docs/lexers/'\fI\%any lexer alias
supported by Pygments\fP\X'tty: link'\&. If it is not
given, the setting of \fI\%highlight\fP directive will be used. If not
set, \X'tty: link #confval-highlight_language'\fI\%highlight_language\fP\X'tty: link' will be used. To display a code example
\fIinline\fP within other text, rather than as a separate block, you can use the
\X'tty: link #role-code'\fI\%code\fP\X'tty: link' role instead.
.sp
Changed in version 2.0: The \fBlanguage\fP argument becomes optional.
.sp
options
.INDENT 7.0
.TP
.B :linenos: (no value)
Enable to generate line numbers for the code block:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: ruby
:linenos:
Some more Ruby code.
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B :lineno\-start: number (number)
Set the first line number of the code block. If present, \fBlinenos\fP
option is also automatically activated:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: ruby
:lineno\-start: 10
Some more Ruby code, with line numbering starting at 10.
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.3.
.UNINDENT
.INDENT 7.0
.TP
.B :emphasize\-lines: line numbers (comma separated numbers)
Emphasize particular lines of the code block:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: python
:emphasize\-lines: 3,5
def some_function():
interesting = False
print(\(aqThis line is highlighted.\(aq)
print(\(aqThis one is not...\(aq)
print(\(aq...but this one is.\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.1.
.sp
Changed in version 1.6.6: LaTeX supports the \fBemphasize\-lines\fP option.
.UNINDENT
.INDENT 7.0
.TP
.B :caption: caption of code block (text)
Set a caption to the code block.
.sp
Added in version 1.3.
.UNINDENT
.INDENT 7.0
.TP
.B :name: a label for hyperlink (text)
Define implicit target name that can be referenced by using
\X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'\&. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: python
:caption: this.py
:name: this\-py
print(\(aqExplicit is better than implicit.\(aq)
.EE
.UNINDENT
.UNINDENT
.sp
In order to cross\-reference a code\-block using either the
\X'tty: link #role-ref'\fI\%ref\fP\X'tty: link' or the \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link' role, it is necessary
that both \fBname\fP and \fBcaption\fP be defined. The
argument of \fBname\fP can then be given to \X'tty: link #role-numref'\fI\%numref\fP\X'tty: link'
to generate the cross\-reference. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
See :numref:\(gathis\-py\(ga for an example.
.EE
.UNINDENT
.UNINDENT
.sp
When using \X'tty: link #role-ref'\fI\%ref\fP\X'tty: link', it is possible to generate a cross\-reference
with only \fBname\fP defined, provided an explicit title is
given. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
See :ref:\(gathis code snippet \(ga for an example.
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.3.
.UNINDENT
.INDENT 7.0
.TP
.B :class: class names (a list of class names separated by spaces)
The class name of the graph.
.sp
Added in version 1.4.
.UNINDENT
.INDENT 7.0
.TP
.B :dedent: number (number or no value)
Strip indentation characters from the code block. When number given,
leading N characters are removed. When no argument given, leading spaces
are removed via \X'tty: link https://docs.python.org/3/library/textwrap.html#textwrap.dedent'\fI\%textwrap.dedent()\fP\X'tty: link'\&. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. code\-block:: ruby
:linenos:
:dedent: 4
some ruby code
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.3.
.sp
Changed in version 3.5: Support automatic dedent.
.UNINDENT
.INDENT 7.0
.TP
.B :force: (no value)
If given, minor errors on highlighting are ignored.
.sp
Added in version 2.1.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \&.. literalinclude:: filename
Longer displays of verbatim text may be included by storing the example text
in an external file containing only plain text. The file may be included
using the \fBliteralinclude\fP directive. [3] For example, to include the
Python source file \fBexample.py\fP, use:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.py
.EE
.UNINDENT
.UNINDENT
.sp
The file name is usually relative to the current file\(aqs path. However, if
it is absolute (starting with \fB/\fP), it is relative to the top source
directory.
.sp
\fBAdditional options\fP
.sp
Like \fI\%code\-block\fP, the directive supports the \fBlinenos\fP flag
option to switch on line numbers, the \fBlineno\-start\fP option to select the
first line number, the \fBemphasize\-lines\fP option to emphasize particular
lines, the \fBname\fP option to provide an implicit target name, the
\fBdedent\fP option to strip indentation characters for the code block, and a
\fBlanguage\fP option to select a language different from the current file\(aqs
standard language. In addition, it supports the \fBcaption\fP option; however,
this can be provided with no argument to use the filename as the caption.
Example with options:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.rb
:language: ruby
:emphasize\-lines: 12,15\-18
:linenos:
.EE
.UNINDENT
.UNINDENT
.sp
Tabs in the input are expanded if you give a \fBtab\-width\fP option with the
desired tab width.
.sp
Include files are assumed to be encoded in the \X'tty: link #confval-source_encoding'\fI\%source_encoding\fP\X'tty: link'\&.
If the file has a different encoding, you can specify it with the
\fBencoding\fP option:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.py
:encoding: latin\-1
.EE
.UNINDENT
.UNINDENT
.sp
The directive also supports including only parts of the file. If it is a
Python module, you can select a class, function or method to include using
the \fBpyobject\fP option:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.py
:pyobject: Timer.start
.EE
.UNINDENT
.UNINDENT
.sp
This would only include the code lines belonging to the \fBstart()\fP method
in the \fBTimer\fP class within the file.
.sp
Alternately, you can specify exactly which lines to include by giving a
\fBlines\fP option:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.py
:lines: 1,3,5\-10,20\-
.EE
.UNINDENT
.UNINDENT
.sp
This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
.sp
Another way to control which part of the file is included is to use the
\fBstart\-after\fP and \fBend\-before\fP options (or only one of them). If
\fBstart\-after\fP is given as a string option, only lines that follow the
first line containing that string are included. If \fBend\-before\fP is given
as a string option, only lines that precede the first lines containing that
string are included. The \fBstart\-at\fP and \fBend\-at\fP options behave in a
similar way, but the lines containing the matched string are included.
.sp
\fBstart\-after\fP/\fBstart\-at\fP and \fBend\-before\fP/\fBend\-at\fP can have same string.
\fBstart\-after\fP/\fBstart\-at\fP filter lines before the line that contains
option string (\fBstart\-at\fP will keep the line). Then \fBend\-before\fP/\fBend\-at\fP
filter lines after the line that contains option string (\fBend\-at\fP will keep
the line and \fBend\-before\fP skip the first line).
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
If you want to select only \fB[second\-section]\fP of ini file like the
following, you can use \fB:start\-at: [second\-section]\fP and
\fB:end\-before: [third\-section]\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
[first\-section]
var_in_first=true
[second\-section]
var_in_second=true
[third\-section]
var_in_third=true
.EE
.UNINDENT
.UNINDENT
.sp
Useful cases of these option is working with tag comments.
\fB:start\-after: [initialize]\fP and \fB:end\-before: [initialized]\fP options
keep lines between comments:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if __name__ == \(dq__main__\(dq:
# [initialize]
app.start(\(dq:8000\(dq)
# [initialized]
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
When lines have been selected in any of the ways described above, the line
numbers in \fBemphasize\-lines\fP refer to those selected lines, counted
consecutively starting at \fB1\fP\&.
.sp
When specifying particular parts of a file to display, it can be useful to
display the original line numbers. This can be done using the
\fBlineno\-match\fP option, which is however allowed only when the selection
consists of contiguous lines.
.sp
You can prepend and/or append a line to the included code, using the
\fBprepend\fP and \fBappend\fP option, respectively. This is useful e.g. for
highlighting PHP code that doesn\(aqt include the \fB\fP markers.
.sp
If you want to show the diff of the code, you can specify the old file by
giving a \fBdiff\fP option:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. literalinclude:: example.py
:diff: example.py.orig
.EE
.UNINDENT
.UNINDENT
.sp
This shows the diff between \fBexample.py\fP and \fBexample.py.orig\fP with
unified diff format.
.sp
A \fBforce\fP option can ignore minor errors on highlighting.
.sp
Changed in version 0.4.3: Added the \fBencoding\fP option.
.sp
Changed in version 0.6: Added the \fBpyobject\fP, \fBlines\fP, \fBstart\-after\fP and \fBend\-before\fP
options, as well as support for absolute filenames.
.sp
Changed in version 1.0: Added the \fBprepend\fP, \fBappend\fP, and \fBtab\-width\fP options.
.sp
Changed in version 1.3: Added the \fBdiff\fP, \fBlineno\-match\fP, \fBcaption\fP, \fBname\fP, and
\fBdedent\fP options.
.sp
Changed in version 1.4: Added the \fBclass\fP option.
.sp
Changed in version 1.5: Added the \fBstart\-at\fP, and \fBend\-at\fP options.
.sp
Changed in version 1.6: With both \fBstart\-after\fP and \fBlines\fP in use, the first line as per
\fBstart\-after\fP is considered to be with line number \fB1\fP for \fBlines\fP\&.
.sp
Changed in version 2.1: Added the \fBforce\fP option.
.sp
Changed in version 3.5: Support automatic dedent.
.UNINDENT
.SS Glossary
.INDENT 0.0
.TP
.B \&.. glossary::
This directive must contain a reST definition\-list\-like markup with terms and
definitions. The definitions will then be referenceable with the
\X'tty: link #role-term'\fI\%term\fP\X'tty: link' role. Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. glossary::
environment
A structure where information about all documents under the root is
saved, and used for cross\-referencing. The environment is pickled
after the parsing stage, so that successive runs only need to read
and parse new and changed documents.
source directory
The directory which, including its subdirectories, contains all
source files for one Sphinx project.
.EE
.UNINDENT
.UNINDENT
.sp
In contrast to regular definition lists, \fImultiple\fP terms per entry are
allowed, and inline markup is allowed in terms. You can link to all of the
terms. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. glossary::
term 1
term 2
Definition of both terms.
.EE
.UNINDENT
.UNINDENT
.sp
(When the glossary is sorted, the first term determines the sort order.)
.sp
If you want to specify \(dqgrouping key\(dq for general index entries, you can put
a \(dqkey\(dq as \(dqterm : key\(dq. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. glossary::
term 1 : A
term 2 : B
Definition of both terms.
.EE
.UNINDENT
.UNINDENT
.sp
Note that \(dqkey\(dq is used for grouping key as is.
The \(dqkey\(dq isn\(aqt normalized; key \(dqA\(dq and \(dqa\(dq become different groups.
The whole characters in \(dqkey\(dq is used instead of a first character; it is
used for \(dqCombining Character Sequence\(dq and \(dqSurrogate Pairs\(dq grouping key.
.sp
In i18n situation, you can specify \(dqlocalized term : key\(dq even if original
text only have \(dqterm\(dq part. In this case, translated \(dqlocalized term\(dq will be
categorized in \(dqkey\(dq group.
.sp
Added in version 0.6: You can now give the glossary directive a \fB:sorted:\fP flag that will
automatically sort the entries alphabetically.
.sp
Changed in version 1.1: Now supports multiple terms and inline markup in terms.
.sp
Changed in version 1.4: Index key for glossary term should be considered \fIexperimental\fP\&.
.sp
Changed in version 4.4: In internationalized documentation, the \fB:sorted:\fP flag sorts
according to translated terms.
.UNINDENT
.SS Meta\-information markup
.INDENT 0.0
.TP
.B \&.. sectionauthor:: name
Identifies the author of the current section. The argument should include
the author\(aqs name such that it can be used for presentation and email
address. The domain name portion of the address should be lower case.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. sectionauthor:: Guido van Rossum
.EE
.UNINDENT
.UNINDENT
.sp
By default, this markup isn\(aqt reflected in the output in any way (it helps
keep track of contributions), but you can set the configuration value
\X'tty: link #confval-show_authors'\fI\%show_authors\fP\X'tty: link' to \fBTrue\fP to make them produce a paragraph in the
output.
.UNINDENT
.INDENT 0.0
.TP
.B \&.. codeauthor:: name
The \fI\%codeauthor\fP directive, which can appear multiple times, names
the authors of the described code, just like \fI\%sectionauthor\fP names
the author(s) of a piece of documentation. It too only produces output if
the \X'tty: link #confval-show_authors'\fI\%show_authors\fP\X'tty: link' configuration value is \fBTrue\fP\&.
.UNINDENT
.SS Index\-generating markup
.sp
Sphinx automatically creates index entries from all object descriptions (like
functions, classes or attributes) like discussed in
\fI\%Domains\fP\&.
.sp
However, there is also explicit markup available, to make the index more
comprehensive and enable index entries in documents where information is not
mainly contained in information units, such as the language reference.
.INDENT 0.0
.TP
.B \&.. index::
This directive contains one or more index entries. Each entry consists of a
type and a value, separated by a colon.
.sp
For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index::
single: execution; context
pair: module; __main__
pair: module; sys
triple: module; search; path
seealso: scope
The execution context
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&...
.EE
.UNINDENT
.UNINDENT
.sp
This directive contains five entries, which will be converted to entries in
the generated index which link to the exact location of the index statement
(or, in case of offline media, the corresponding page number).
.sp
Since index directives generate cross\-reference targets at their location in
the source, it makes sense to put them \fIbefore\fP the thing they refer to \-\-
e.g. a heading, as in the example above.
.sp
The possible entry types are:
.INDENT 7.0
.TP
.B single
Creates a single index entry.
Can be made a sub\-entry by separating the sub\-entry text with a semicolon
(this notation is also used below to describe what entries are created).
Examples:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: single: execution
single: execution; context
.EE
.UNINDENT
.UNINDENT
.INDENT 7.0
.IP \(bu 2
\fBsingle: execution\fP creates an index entry labelled \fBexecution\fP\&.
.IP \(bu 2
\fBsingle: execution; context\fP creates an sub\-entry of \fBexecution\fP
labelled \fBcontext\fP\&.
.UNINDENT
.TP
.B pair
A shortcut to create two index entries.
The pair of values must be separated by a semicolon.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: pair: loop; statement
.EE
.UNINDENT
.UNINDENT
.sp
This would create two index entries; \fBloop; statement\fP and \fBstatement; loop\fP\&.
.TP
.B triple
A shortcut to create three index entries.
All three values must be separated by a semicolon.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: triple: module; search; path
.EE
.UNINDENT
.UNINDENT
.sp
This would create three index entries; \fBmodule; search path\fP,
\fBsearch; path, module\fP, and \fBpath; module search\fP\&.
.TP
.B see
A shortcut to create an index entry that refers to another entry.
Example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: see: entry; other
.EE
.UNINDENT
.UNINDENT
.sp
This would create an index entry referring from \fBentry\fP to \fBother\fP
(i.e. \(aqentry\(aq: See \(aqother\(aq).
.TP
.B seealso
Like \fBsee\fP, but inserts \(aqsee also\(aq instead of \(aqsee\(aq.
.TP
.B module, keyword, operator, object, exception, statement, builtin
These \fBdeprecated\fP shortcuts all create two index entries.
For example, \fBmodule: hashlib\fP creates the entries \fBmodule; hashlib\fP
and \fBhashlib; module\fP\&.
.sp
Deprecated since version 1.0: These Python\-specific entry types are deprecated.
.sp
Changed in version 7.1: Removal version set to Sphinx 9.0.
Using these entry types will now emit warnings with the \fBindex\fP category.
.UNINDENT
.sp
You can mark up \(dqmain\(dq index entries by prefixing them with an exclamation
mark. The references to \(dqmain\(dq entries are emphasized in the generated
index. For example, if two pages contain
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: Python
.EE
.UNINDENT
.UNINDENT
.sp
and one page contains
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: ! Python
.EE
.UNINDENT
.UNINDENT
.sp
then the backlink to the latter page is emphasized among the three backlinks.
.sp
For index directives containing only \(dqsingle\(dq entries, there is a shorthand
notation:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: BNF, grammar, syntax, notation
.EE
.UNINDENT
.UNINDENT
.sp
This creates four index entries.
.sp
Changed in version 1.1: Added \fBsee\fP and \fBseealso\fP types, as well as marking main entries.
.sp
options
.INDENT 7.0
.TP
.B :name: a label for hyperlink (text)
Define implicit target name that can be referenced by using
\X'tty: link #role-ref'\fI\%ref\fP\X'tty: link'\&. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. index:: Python
:name: py\-index
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Added in version 3.0.
.UNINDENT
.INDENT 0.0
.TP
.B :index:
While the \fI\%index\fP directive is a block\-level markup and links to the
beginning of the next paragraph, there is also a corresponding role that sets
the link target directly where it is used.
.sp
The content of the role can be a simple phrase, which is then kept in the
text and used as an index entry. It can also be a combination of text and
index entry, styled like with explicit targets of cross\-references. In that
case, the \(dqtarget\(dq part can be a full entry as described for the directive
above. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
This is a normal reST :index:\(gaparagraph\(ga that contains several
:index:\(gaindex entries \(ga.
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.1.
.UNINDENT
.SS Including content based on tags
.INDENT 0.0
.TP
.B \&.. only::
Include the content of the directive only if the \fIexpression\fP is true. The
expression should consist of tags, like this:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. only:: html and draft
.EE
.UNINDENT
.UNINDENT
.sp
Undefined tags are false, defined tags (via the \fB\-t\fP command\-line option or
within \fBconf.py\fP, see \X'tty: link #conf-tags'\fI\%here\fP\X'tty: link') are true. Boolean
expressions, also using parentheses (like \fB(latex or html) and draft\fP) are
supported.
.sp
The \fIformat\fP and the \fIname\fP of the current builder (\fBhtml\fP, \fBlatex\fP or
\fBtext\fP) are always set as a tag [4]\&. To make the distinction between
format and name explicit, they are also added with the prefix \fBformat_\fP and
\fBbuilder_\fP, e.g. the epub builder defines the tags \fBhtml\fP, \fBepub\fP,
\fBformat_html\fP and \fBbuilder_epub\fP\&.
.sp
These standard tags are set \fIafter\fP the configuration file is read, so they
are not available there.
.sp
All tags must follow the standard Python identifier syntax as set out in
the \X'tty: link https://docs.python.org/3/reference/lexical_analysis.html#identifiers'\fI\%Identifiers and keywords\fP\X'tty: link'
documentation. That is, a tag expression may only consist of tags that
conform to the syntax of Python variables. In ASCII, this consists of the
uppercase and lowercase letters \fBA\fP through \fBZ\fP, the underscore \fB_\fP
and, except for the first character, the digits \fB0\fP through \fB9\fP\&.
.sp
Added in version 0.6.
.sp
Changed in version 1.2: Added the name of the builder and the prefixes.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
This directive is designed to control only content of document. It could
not control sections, labels and so on.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Tables
.sp
Use \X'tty: link #rst-tables'\fI\%reStructuredText tables\fP\X'tty: link', i.e. either
.INDENT 0.0
.IP \(bu 2
grid table syntax (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#grid-tables'\fI\%ref\fP\X'tty: link'),
.IP \(bu 2
simple table syntax (\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#simple-tables'\fI\%ref\fP\X'tty: link'),
.IP \(bu 2
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link' syntax,
.IP \(bu 2
or \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link' syntax.
.UNINDENT
.sp
The \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' directive serves as optional wrapper of the \fIgrid\fP and
\fIsimple\fP syntaxes.
.sp
They work fine in HTML output, but rendering tables to LaTeX is complex.
Check the \X'tty: link #confval-latex_table_style'\fI\%latex_table_style\fP\X'tty: link'\&.
.sp
Changed in version 1.6: Merged cells (multi\-row, multi\-column, both) from grid tables containing
complex contents such as multiple paragraphs, blockquotes, lists, literal
blocks, will render correctly to LaTeX output.
.INDENT 0.0
.TP
.B \&.. tabularcolumns:: column spec
This directive influences only the LaTeX output for the next table in
source. The mandatory argument is a column specification (known as an
\(dqalignment preamble\(dq in LaTeX idiom). Please refer to a LaTeX
documentation, such as the \X'tty: link https://en.wikibooks.org/wiki/LaTeX/Tables'\fI\%wiki page\fP\X'tty: link', for basics of such a column
specification.
.sp
Added in version 0.3.
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
\fI\%tabularcolumns\fP conflicts with \fB:widths:\fP option of table
directives. If both are specified, \fB:widths:\fP option will be ignored.
.UNINDENT
.UNINDENT
.sp
Sphinx will render tables with more than 30 rows with \fBlongtable\fP\&.
Besides the \fBl\fP, \fBr\fP, \fBc\fP and \fBp{width}\fP column specifiers, one can
also use \fB\eX{a}{b}\fP (new in version 1.5) which configures the column
width to be a fraction \fBa/b\fP of the total line width and \fB\eY{f}\fP (new
in version 1.6) where \fBf\fP is a decimal: for example \fB\eY{0.2}\fP means that
the column will occupy \fB0.2\fP times the line width.
.sp
When this directive is used for a table with at most 30 rows, Sphinx will
render it with \fBtabulary\fP\&. One can then use specific column types \fBL\fP
(left), \fBR\fP (right), \fBC\fP (centered) and \fBJ\fP (justified). They have
the effect of a \fBp{width}\fP (i.e. each cell is a LaTeX \fB\eparbox\fP) with
the specified internal text alignment and an automatically computed
\fBwidth\fP\&.
.sp
\fBWARNING:\fP
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
Cells that contain list\-like elements such as object descriptions,
blockquotes or any kind of lists are not compatible with the \fBLRCJ\fP
column types. The column type must then be some \fBp{width}\fP with an
explicit \fBwidth\fP (or \fB\eX{a}{b}\fP or \fB\eY{f}\fP).
.IP \(bu 2
Literal blocks do not work with \fBtabulary\fP at all. Sphinx will
fall back to \fBtabular\fP or \fBlongtable\fP environments and generate a
suitable column specification.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
In absence of the \fI\%tabularcolumns\fP directive, and for a table with at
most 30 rows and no problematic cells as described in the above warning,
Sphinx uses \fBtabulary\fP and the \fBJ\fP column\-type for every column.
.sp
Changed in version 1.6: Formerly, the \fBL\fP column\-type was used (text is flushed\-left). To revert
to this, include \fB\enewcolumntype{T}{L}\fP in the LaTeX preamble, as in fact
Sphinx uses \fBT\fP and sets it by default to be an alias of \fBJ\fP\&.
.sp
\fBHINT:\fP
.INDENT 0.0
.INDENT 3.5
A frequent issue with \fBtabulary\fP is that columns with little contents
appear to be \(dqsqueezed\(dq. One can add to the LaTeX preamble for example
\fB\esetlength{\etymin}{40pt}\fP to ensure a minimal column width of \fB40pt\fP,
the \fBtabulary\fP default of \fB10pt\fP being too small.
.UNINDENT
.UNINDENT
.sp
\fBHINT:\fP
.INDENT 0.0
.INDENT 3.5
To force usage of the LaTeX \fBlongtable\fP environment pass \fBlongtable\fP as
a \fB:class:\fP option to \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link', \X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table'\fI\%csv\-table\fP\X'tty: link', or
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table'\fI\%list\-table\fP\X'tty: link'\&. Use \X'tty: link #rstclass'\fI\%rst\-class\fP\X'tty: link' for other tables.
.UNINDENT
.UNINDENT
.SS Math
.sp
The input language for mathematics is LaTeX markup. This is the de\-facto
standard for plain\-text math notation and has the added advantage that no
further translation is necessary when building LaTeX output.
.sp
Keep in mind that when you put math markup in \fBPython docstrings\fP read by
\X'tty: link #module-sphinx.ext.autodoc'\fI\%autodoc\fP\X'tty: link', you either have to double all backslashes,
or use Python raw strings (\fBr\(dqraw\(dq\fP).
.INDENT 0.0
.TP
.B \&.. math::
Directive for displayed math (math that takes the whole line for itself).
.sp
The directive supports multiple equations, which should be separated by a
blank line:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. math::
(a + b)^2 = a^2 + 2ab + b^2
(a \- b)^2 = a^2 \- 2ab + b^2
.EE
.UNINDENT
.UNINDENT
.sp
In addition, each single equation is set within a \fBsplit\fP environment,
which means that you can have multiple aligned lines in an equation,
aligned at \fB&\fP and separated by \fB\e\e\fP:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. math::
(a + b)^2 &= (a + b)(a + b) \e\e
&= a^2 + 2ab + b^2
.EE
.UNINDENT
.UNINDENT
.sp
For more details, look into the documentation of the \X'tty: link https://www.ams.org/publications/authors/tex/amslatex'\fI\%AmSMath LaTeX
package\fP\X'tty: link'\&.
.sp
When the math is only one line of text, it can also be given as a directive
argument:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. math:: (a + b)^2 = a^2 + 2ab + b^2
.EE
.UNINDENT
.UNINDENT
.sp
Normally, equations are not numbered. If you want your equation to get a
number, use the \fBlabel\fP option. When given, it selects an internal label
for the equation, by which it can be cross\-referenced, and causes an equation
number to be issued. See \X'tty: link #role-eq'\fI\%eq\fP\X'tty: link' for an example. The numbering
style depends on the output format.
.sp
There is also an option \fBnowrap\fP that prevents any wrapping of the given
math in a math environment. When you give this option, you must make sure
yourself that the math is properly set up. For example:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. math::
:nowrap:
\ebegin{eqnarray}
y & = & ax^2 + bx + c \e\e
f(x) & = & x^2 + 2xy + y^2
\eend{eqnarray}
.EE
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBSEE ALSO:\fP
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \X'tty: link #math-support'\fI\%Math support for HTML outputs in Sphinx\fP\X'tty: link'
Rendering options for math with HTML builders.
.TP
.B \X'tty: link #confval-latex_engine'\fI\%latex_engine\fP\X'tty: link'
Explains how to configure LaTeX builder to support Unicode literals in
math mark\-up.
.UNINDENT
.UNINDENT
.UNINDENT
.SS Grammar production displays
.sp
Special markup is available for displaying the productions of a formal grammar.
The markup is simple and does not attempt to model all aspects of BNF (or any
derived forms), but provides enough to allow context\-free grammars to be
displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
the definition of the symbol. There is this directive:
.INDENT 0.0
.TP
.B \&.. productionlist:: [productionGroup]
This directive is used to enclose a group of productions. Each production
is given on a single line and consists of a name, separated by a colon from
the following definition. If the definition spans multiple lines, each
continuation line must begin with a colon placed at the same column as in
the first line.
Blank lines are not allowed within \fBproductionlist\fP directive arguments.
.sp
The definition can contain token names which are marked as interpreted text
(e.g., \(dq\fBsum ::= \(gainteger\(ga \(dq+\(dq \(gainteger\(ga\fP\(dq) \-\- this generates
cross\-references to the productions of these tokens. Outside of the
production list, you can reference to token productions using
\X'tty: link #role-token'\fI\%token\fP\X'tty: link'\&.
.sp
The \fIproductionGroup\fP argument to \fI\%productionlist\fP serves to
distinguish different sets of production lists that belong to different
grammars. Multiple production lists with the same \fIproductionGroup\fP thus
define rules in the same scope.
.sp
Inside of the production list, tokens implicitly refer to productions
from the current group. You can refer to the production of another
grammar by prefixing the token with its group name and a colon, e.g,
\(dq\fBotherGroup:sum\fP\(dq. If the group of the token should not be shown in
the production, it can be prefixed by a tilde, e.g.,
\(dq\fB~otherGroup:sum\fP\(dq. To refer to a production from an unnamed
grammar, the token should be prefixed by a colon, e.g., \(dq\fB:sum\fP\(dq.
.sp
Outside of the production list,
if you have given a \fIproductionGroup\fP argument you must prefix the
token name in the cross\-reference with the group name and a colon,
e.g., \(dq\fBmyGroup:sum\fP\(dq instead of just \(dq\fBsum\fP\(dq.
If the group should not be shown in the title of the link either
an explicit title can be given (e.g., \(dq\fBmyTitle \fP\(dq),
or the target can be prefixed with a tilde (e.g., \(dq\fB~myGroup:sum\fP\(dq).
.sp
Note that no further reST parsing is done in the production, so that you
don\(aqt have to escape \fB*\fP or \fB|\fP characters.
.UNINDENT
.sp
The following is an example taken from the Python Reference Manual:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&.. productionlist::
try_stmt: try1_stmt | try2_stmt
try1_stmt: \(dqtry\(dq \(dq:\(dq \(gasuite\(ga
: (\(dqexcept\(dq [\(gaexpression\(ga [\(dq,\(dq \(gatarget\(ga]] \(dq:\(dq \(gasuite\(ga)+
: [\(dqelse\(dq \(dq:\(dq \(gasuite\(ga]
: [\(dqfinally\(dq \(dq:\(dq \(gasuite\(ga]
try2_stmt: \(dqtry\(dq \(dq:\(dq \(gasuite\(ga
: \(dqfinally\(dq \(dq:\(dq \(gasuite\(ga
.EE
.UNINDENT
.UNINDENT
.SH FOOTNOTES
.IP [1] 5
The LaTeX writer only refers the \fBmaxdepth\fP option of first toctree
directive in the document.
.IP [2] 5
A note on available globbing syntax: you can use the standard shell
constructs \fB*\fP, \fB?\fP, \fB[...]\fP and \fB[!...]\fP with the feature that
these all don\(aqt match slashes. A double star \fB**\fP can be used to
match any sequence of characters \fIincluding\fP slashes.
.IP [3] 5
There is a standard \fB\&.. include\fP directive, but it raises errors if the
file is not found. This one only emits a warning.
.IP [4] 5
For most builders name and format are the same. At the moment only
builders derived from the html builder distinguish between the builder
format and the builder name.
.sp
Note that the current builder tag is not available in \fBconf.py\fP, it is
only available after the builder is initialized.
.SS Field Lists
.sp
\X'tty: link #rst-field-lists'\fI\%As previously discussed\fP\X'tty: link', field lists are sequences of
fields marked up like this:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
:fieldname: Field content
.EE
.UNINDENT
.UNINDENT
.sp
Sphinx extends standard docutils behavior for field lists and adds some extra
functionality that is covered in this section.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The values of field lists will be parsed as
strings. You cannot use Python collections such as lists or dictionaries.
.UNINDENT
.UNINDENT
.SS File\-wide metadata
.sp
A field list near the top of a file is normally parsed by docutils as the
\fIdocinfo\fP and shown on the page. However, in Sphinx, a field list preceding
any other markup is moved from the \fIdocinfo\fP to the Sphinx environment as
document metadata, and is not displayed in the output.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
A field list appearing after the document title \fIwill\fP be part of the
\fIdocinfo\fP as normal and will be displayed in the output.
.UNINDENT
.UNINDENT
.SS Special metadata fields
.sp
Sphinx provides custom behavior for bibliographic fields compared to docutils.
.sp
At the moment, these metadata fields are recognized:
.INDENT 0.0
.TP
.B \fBtocdepth\fP
The maximum depth for a table of contents of this file.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
:tocdepth: 2
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
This metadata effects to the depth of local toctree. But it does not
effect to the depth of \fIglobal\fP toctree. So this would not be change
the sidebar of some themes which uses global one.
.UNINDENT
.UNINDENT
.sp
Added in version 0.4.
.TP
.B \fBnocomments\fP
If set, the web application won\(aqt display a comment form for a page
generated from this source file.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
:nocomments:
.EE
.UNINDENT
.UNINDENT
.TP
.B \fBorphan\fP
If set, warnings about this file not being included in any toctree will be
suppressed.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
:orphan:
.EE
.UNINDENT
.UNINDENT
.sp
Added in version 1.0.
.TP
.B \fBnosearch\fP
If set, full text search for this file is disabled.
.INDENT 7.0
.INDENT 3.5
.sp
.EX
:nosearch:
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 7.0
.INDENT 3.5
object search is still available even if \fBnosearch\fP option is set.
.UNINDENT
.UNINDENT
.sp
Added in version 3.0.
.UNINDENT
.SS MOVED: Domains
.SS MOVED: Basic Markup
.sp
See \fI\%Domains\fP\&.
.SS MOVED: Python Domain
.sp
See \fI\%The Python Domain\fP\&.
.SS MOVED: C Domain
.sp
See \fI\%The C Domain\fP\&.
.SS MOVED: C++ Domain
.sp
See \fI\%The C++ Domain\fP\&.
.SS MOVED: Standard Domain
.sp
See \fI\%The Standard Domain\fP\&.
.SS MOVED: JavaScript Domain
.sp
See \fI\%The JavaScript Domain\fP\&.
.SS MOVED: reStructuredText Domain
.sp
See \fI\%The reStructuredText Domain\fP\&.
.SS MOVED: Math Domain
.sp
See \fI\%The Mathematics Domain\fP\&.
.SS MOVED: More domains
.sp
See \fI\%Domains\fP\&.
.SS Markdown
.sp
\X'tty: link https://daringfireball.net/projects/markdown/'\fI\%Markdown\fP\X'tty: link' is a lightweight markup language with a simplistic plain text
formatting syntax. It exists in many syntactically different \fIflavors\fP\&. To
support Markdown\-based documentation, Sphinx can use \X'tty: link https://myst-parser.readthedocs.io/en/latest/'\fI\%MyST\-Parser\fP\X'tty: link'\&.
MyST\-Parser is a Docutils bridge to \X'tty: link https://github.com/executablebooks/markdown-it-py'\fI\%markdown\-it\-py\fP\X'tty: link', a Python package for
parsing the \X'tty: link https://commonmark.org/'\fI\%CommonMark\fP\X'tty: link' Markdown flavor.
.SS Configuration
.sp
To configure your Sphinx project for Markdown support, proceed as follows:
.INDENT 0.0
.IP 1. 3
Install the Markdown parser \fIMyST\-Parser\fP:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
pip install \-\-upgrade myst\-parser
.EE
.UNINDENT
.UNINDENT
.IP 2. 3
Add \fImyst_parser\fP to the
\X'tty: link #confval-extensions'\fI\%list of configured extensions\fP\X'tty: link':
.INDENT 3.0
.INDENT 3.5
.sp
.EX
extensions = [\(aqmyst_parser\(aq]
.EE
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 3.0
.INDENT 3.5
MyST\-Parser requires Sphinx 2.1 or newer.
.UNINDENT
.UNINDENT
.IP 3. 3
If you want to use Markdown files with extensions other than \fB\&.md\fP, adjust
the \X'tty: link #confval-source_suffix'\fI\%source_suffix\fP\X'tty: link' variable. The following example configures
Sphinx to parse all files with the extensions \fB\&.md\fP and \fB\&.txt\fP as
Markdown:
.INDENT 3.0
.INDENT 3.5
.sp
.EX
source_suffix = {
\(aq.rst\(aq: \(aqrestructuredtext\(aq,
\(aq.txt\(aq: \(aqmarkdown\(aq,
\(aq.md\(aq: \(aqmarkdown\(aq,
}
.EE
.UNINDENT
.UNINDENT
.IP 4. 3
You can further configure \fIMyST\-Parser\fP to allow custom syntax that
standard \fICommonMark\fP doesn\(aqt support. Read more in the \X'tty: link https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html'\fI\%MyST\-Parser
documentation\fP\X'tty: link'\&.
.UNINDENT
.SS Cross\-referencing syntax
.sp
Cross\-references are generated by many semantic interpreted text roles.
Basically, you only need to write \fB:role:\(gatarget\(ga\fP, and a link will be
created to the item named \fItarget\fP of the type indicated by \fIrole\fP\&. The link\(aqs
text will be the same as \fItarget\fP\&.
.sp
There are some additional facilities, however, that make cross\-referencing
roles more versatile:
.INDENT 0.0
.IP \(bu 2
You may supply an explicit title and reference target, like in reST direct
hyperlinks: \fB:role:\(gatitle \(ga\fP will refer to \fItarget\fP, but the link
text will be \fItitle\fP\&.
.IP \(bu 2
If you prefix the content with \fB!\fP, no reference/hyperlink will be created.
.IP \(bu 2
If you prefix the content with \fB~\fP, the link text will only be the last
component of the target. For example, \fB:py:meth:\(ga~Queue.Queue.get\(ga\fP will
refer to \fBQueue.Queue.get\fP but only display \fBget\fP as the link text. This
does not work with all cross\-reference roles, but is domain specific.
.sp
In HTML output, the link\(aqs \fBtitle\fP attribute (that is e.g. shown as a
tool\-tip on mouse\-hover) will always be the full target name.
.UNINDENT
.SS Cross\-referencing anything
.INDENT 0.0
.TP
.B :any:
Added in version 1.3.
.sp
This convenience role tries to do its best to find a valid target for its
reference text.
.INDENT 7.0
.IP \(bu 2
First, it tries standard cross\-reference targets that would be referenced
by \fI\%doc\fP, \fI\%ref\fP or \fI\%option\fP\&.
.sp
Custom objects added to the standard domain by extensions (see
\X'tty: link #sphinx.application.Sphinx.add_object_type'\fI\%Sphinx.add_object_type()\fP\X'tty: link') are also searched.
.IP \(bu 2
Then, it looks for objects (targets) in all loaded domains. It is up to
the domains how specific a match must be. For example, in the Python
domain a reference of \fB:any:\(gaBuilder\(ga\fP would match the
\fBsphinx.builders.Builder\fP class.
.UNINDENT
.sp
If none or multiple targets are found, a warning will be emitted. In the
case of multiple targets, you can change \(dqany\(dq to a specific role.
.sp
This role is a good candidate for setting \X'tty: link #confval-default_role'\fI\%default_role\fP\X'tty: link'\&. If you
do, you can write cross\-references without a lot of markup overhead. For
example, in this Python function documentation:
.INDENT 7.0
.INDENT 3.5
.sp
.EX
\&.. function:: install()
This function installs a \(gahandler\(ga for every signal known by the
\(gasignal\(ga module. See the section \(gaabout\-signals\(ga for more information.
.EE
.UNINDENT
.UNINDENT
.sp
there could be references to a glossary term (usually \fB:term:\(gahandler\(ga\fP), a
Python module (usually \fB:py:mod:\(gasignal\(ga\fP or \fB:mod:\(gasignal\(ga\fP) and a
section (usually \fB:ref:\(gaabout\-signals\(ga\fP).
.sp
The \fI\%any\fP role also works together with the
\X'tty: link #module-sphinx.ext.intersphinx'\fI\%intersphinx\fP\X'tty: link' extension: when no local cross\-reference is
found, all object types of intersphinx inventories are also searched.
.UNINDENT
.SS Cross\-referencing objects
.sp
These roles are described with their respective domains:
.INDENT 0.0
.IP \(bu 2
\X'tty: link #python-roles'\fI\%Python\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #c-roles'\fI\%C\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #cpp-roles'\fI\%C++\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #js-roles'\fI\%JavaScript\fP\X'tty: link'
.IP \(bu 2
\X'tty: link #rst-roles'\fI\%ReST\fP\X'tty: link'
.UNINDENT
.SS Cross\-referencing arbitrary locations
.INDENT 0.0
.TP
.B :ref:
To support cross\-referencing to arbitrary locations in any document, the
standard reST labels are used. For this to work label names must be unique
throughout the entire documentation. There are two ways in which you can
refer to labels:
.INDENT 7.0
.IP \(bu 2
If you place a label directly before a section title, you can reference to
it with \fB:ref:\(galabel\-name\(ga\fP\&. For example:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
\&.. _my\-reference\-label:
Section to cross\-reference
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
This is the text of the section.
It refers to the section itself, see :ref:\(gamy\-reference\-label\(ga.
.EE
.UNINDENT
.UNINDENT
.sp
The \fB:ref:\fP role would then generate a link to the section, with the
link title being \(dqSection to cross\-reference\(dq. This works just as well
when section and reference are in different source files.
.sp
Automatic labels also work with figures. For example:
.INDENT 2.0
.INDENT 3.5
.sp
.EX
\&.. _my\-figure:
\&.. figure:: whatever
Figure caption
.EE
.UNINDENT
.UNINDENT
.sp
In this case, a reference \fB:ref:\(gamy\-figure\(ga\fP would insert a reference
to the figure with link text \(dqFigure caption\(dq.
.sp
The same works for tables that are given an explicit caption using the
\X'tty: link https://docutils.sourceforge.io/docs/ref/rst/directives.html#table'\fI\%table\fP\X'tty: link' directive.
.IP \(bu 2
Labels that aren\(aqt placed before a section title can still be referenced,
but you must give the link an explicit title, using this syntax:
\fB:ref:\(gaLink title