reStructuredText Primer — Sphinx documentation

reStructuredText Primer — Sphinx documentation
Sphinx
Documentation
Using Sphinx
reStructuredText
reStructuredText Primer
On this page
reStructuredText Primer
Paragraphs
Inline markup
Lists and Quote-like blocks
Literal blocks
Doctest blocks
Tables
Hyperlinks
External links
Internal links
Sections
Field Lists
Roles
Explicit Markup
Directives
Images
Footnotes
Citations
Substitutions
Comments
HTML Metadata
Source encoding
Gotchas
The Basics
Installing Sphinx
Getting started
Build your first project
User guide
Using Sphinx
reStructuredText
reStructuredText Primer
Roles
Directives
Field Lists
MOVED: Domains
Markdown
Cross-references
Configuration
Builders
Domains
Extensions
HTML theming
Internationalization
Sphinx Web Support
Extending Sphinx
Sphinx API
LaTeX customization
Community
Get support
Contribute to Sphinx
Sphinx FAQ
Sphinx authors
Reference
Command-line tools
Configuration
Extensions
reStructuredText
reStructuredText Primer
Roles
Directives
Field Lists
MOVED: Domains
Glossary
Changelog
Projects using Sphinx
reStructuredText Primer
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 reStructuredText was designed to be a simple, unobtrusive markup
language, this will not take too long.
See also
The authoritative
reStructuredText User Documentation
The “ref” links in this document link to the description of
the individual constructs in the reStructuredText reference.
Paragraphs
The paragraph (
ref
) is the most basic block
in a reStructuredText document.
Paragraphs are simply chunks of text separated by one or more blank lines.
As in Python, indentation is significant in reStructuredText,
so all lines of the same paragraph must be left-aligned
to the same level of indentation.
Inline markup
The standard reStructuredText inline markup is quite simple: use
one asterisk:
*text*
for emphasis (italics),
two asterisks:
**text**
for strong emphasis (boldface), and
backquotes:
``text``
for code samples.
If asterisks or backquotes appear in running text and could be confused with
inline markup delimiters, they have to be escaped with a backslash.
Be aware of some restrictions of this markup:
it may not be nested,
content may not start or end with whitespace:
text*
is wrong,
it must be separated from surrounding text by non-word characters. Use a
backslash escaped space to work around that:
thisis\
*one*\
word
These restrictions may be lifted in future versions of the docutils.
It is also possible to replace or expand upon some of this inline markup with
roles. Refer to
Roles
for more information.
Lists and Quote-like blocks
List markup (
ref
) 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
sign:
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.
Nested lists are possible, but be aware that they must be separated from the
parent list items by blank lines:
this is
a list
with a nested list
and some subitems
and here the parent list continues
Definition lists (
ref
) are created as follows:
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.
Note that the term cannot have more than one line of text.
Quoted paragraphs (
ref
) are created by just indenting
them more than the surrounding paragraphs.
Line blocks (
ref
) are a way of preserving line breaks:
These lines are
broken exactly like in
the source file.
There are also several more special blocks available:
field lists (
ref
, with caveats noted in
Field Lists
option lists (
ref
quoted literal blocks (
ref
doctest blocks (
ref
Literal blocks
Literal code blocks (
ref
) are introduced by ending a
paragraph with the special marker
::
. The literal block must be indented
(and, like all paragraphs, separated from the surrounding ones by blank
lines):
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.
The handling of the
::
marker is smart:
If it occurs as a paragraph of its own, that paragraph is completely left out
of the document.
If it is preceded by whitespace, the marker is removed.
If it is preceded by non-whitespace, the marker is replaced by a single
colon.
That way, the second sentence in the above example’s first paragraph would be
rendered as “The next paragraph is a code sample:”.
Code highlighting can be enabled for these literal blocks on a document-wide
basis using the
highlight
directive and on a project-wide basis
using the
highlight_language
configuration option. The
code-block
directive can be used to set highlighting on a
block-by-block basis. These directives are discussed later.
Doctest blocks
Doctest blocks (
ref
) are interactive Python sessions
cut-and-pasted into docstrings. They do not require the
literal blocks
syntax. The doctest block must end
with a blank line and should
not
end with an unused prompt:
>>> 1 + 1
Tables
For
grid tables
ref
), you have to “paint” the cell
grid yourself. They look like this:
+------------------------+------------+----------+----------+
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 | ... | ... | |
+------------------------+------------+----------+----------+
Simple tables
ref
) 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:
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
Two more syntaxes are supported:
CSV tables
and
List tables
. They use an
explicit markup block
. Refer to
Tables
for more information.
Hyperlinks
External links
URLs and email addresses in text are automatically linked and do not need
explicit markup at all.
For example,
is written with no special markup
in the source of this document, and is recognised as an external hyperlink.
To create text with a link, the best approach is generally to put the URL
below the paragraph as follows (
ref
):
This is a paragraph that contains
`a link`_
..
_a link:
This keeps the paragraph more readable in source code.
Alternatively, you can embed the URL within the prose for an ‘inline link’.
This can lead to longer lines, but has the benefit of keeping the link text
and the URL pointed to in the same place.
This uses the following syntax:
`Link
text
`__
ref
).
Important
There must be a space between the link text
and the opening angle bracket (’
’) for the URL.
Tip
Use two trailing underscores when embedding the URL.
Technically, a single underscore works as well,
but that would create a named reference instead of an anonymous one.
Named references typically do not have a benefit when the URL is embedded.
Moreover, they have the disadvantage that you must make sure that you
do not use the same “Link text” for another link in your document.
You can also separate the link and the target definition (
ref
), like this:
This is a paragraph that contains
`a link`_
..
_a link:
Internal links
Internal linking is done via a special reStructuredText role provided by Sphinx,
see the section on specific markup,
Cross-referencing arbitrary locations
Sections
Section headers (
ref
) are created by underlining (and
optionally overlining) the section title with a punctuation character, at least
as long as the text:
=================
This is a heading
=================
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
Python Developer’s Guide for documenting
which you may
follow:
with overline, for parts
with overline, for chapters
for sections
for subsections
for subsubsections
for paragraphs
Of course, you are free to use your own marker characters (see the reStructuredText
documentation), and use a deeper nesting level, but keep in mind that most
target formats (HTML, LaTeX) have a limited supported nesting depth.
Field Lists
Field lists (
ref
) are sequences of fields marked up like
this:
:fieldname:
Field content
They are commonly used in Python documentation:
def my_function(my_arg, my_other_arg):
"""A 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).
"""
Sphinx extends standard docutils behavior and intercepts field lists specified
at the beginning of documents. Refer to
Field Lists
for more
information.
Roles
A role or “custom interpreted text role” (
ref
) 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
:rolename:`content`
Docutils supports the following roles:
emphasis
– equivalent of
*emphasis*
strong
– equivalent of
**strong**
literal
– equivalent of
``literal``
subscript
– subscript text
superscript
– superscript text
title-reference
– for titles of books, periodicals, and other
materials
Refer to
Roles
for roles added by Sphinx.
Explicit Markup
“Explicit markup” (
ref
) is used in
reStructuredText for most constructs that need special handling, such as footnotes,
specially-highlighted paragraphs, comments, and generic directives.
An explicit markup block begins with a line starting with
..
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.)
Directives
A directive (
ref
) is a generic block of explicit markup.
Along with roles, it is one of the extension mechanisms of reStructuredText,
and Sphinx makes heavy use of it.
Docutils supports the following directives:
Admonitions:
attention
caution
danger
error
hint
important
note
tip
warning
and the generic
admonition
. (Most themes style only “note” and
“warning” specially.)
Images:
image
(see also
Images
below)
figure
(an image with caption and optional legend)
Additional body elements:
contents
(a local, i.e. for the current file
only, table of contents)
container
(a container with a custom class, useful to generate an
outer