You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document has been placed in the public domain. You
may do with it as you wish. You may copy, modify,
redistribute, reattribute, sell, buy, rent, lease,
destroy, or improve it, quote it at length, excerpt,
incorporate, collate, fold, staple, or mutilate it, or do
anything else to it that your or anyone else's heart
desires.
field name:
This is a generic bibliographic field.
field name 2:
Generic bibliographic fields may contain multiple body elements.
Like this.
Dedication
For Docutils users & co-developers.
Abstract
This document is a demonstration of the reStructuredText markup
language, containing examples of all basic reStructuredText
constructs and many advanced constructs.
Paragraphs contain text and may contain inline markup: emphasis,
strong emphasis, inline literals, standalone hyperlinks
(http://www.python.org), external hyperlinks (Python[5]), internal
cross-references (example), external hyperlinks with embedded URIs
(Python web site), footnote references
(manually numbered [1], anonymous auto-numbered [3], labeled
auto-numbered [2], or symbolic [*]), citation references
([CIT2002]), substitution references (), and inline
hyperlink targets (see Targets below for a reference back to here).
Character-level inline markup is also possible (although exceedingly
ugly!) in reStructuredText. Problems are indicated by
|problematic| text (generated by processing errors; this one is
intentional).
The default role for interpreted text is Title Reference. Here are
some explicit interpreted text roles: a PEP reference (PEP 287); an
RFC reference (RFC 2822); a subscript; a superscript;
and explicit roles for standardinlinemarkup.
Let's test wrapping and whitespace significance in inline literals:
This is an example of --inline-literal --text, --including some--
strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
to see how the text is wrapped. -- ---- -------- Now note the
spacing between the words of this sentence (words
should be grouped in pairs).
If the --pep-references option was supplied, there should be a
live link to PEP 258 here.
Field lists map field names to field bodies, like database
records. They are often part of an extension syntax. They are
an unambiguous variant of RFC 2822 fields.
how arg1 arg2:
The field marker is a colon, the field name, and a colon.
The field body may contain one or more body elements, indented
relative to the field marker.
My theory by A. Elk. Brackets Miss, brackets. This theory goes
as follows and begins now. All brontosauruses are thin at one
end, much much thicker in the middle and then thin again at the
far end. That is my theory, it is mine, and belongs to me and I
own it, and what it is too.
>>> print'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print'(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)
A footnote contains body elements, consistently indented by at
least 3 spaces.
This is the footnote's second paragraph.
[2]
(1, 2) Footnotes may be numbered, either manually (as in [1]) or
automatically using a "#"-prefixed label. This footnote has a
label so it can be referred to from multiple places, both as a
footnote reference ([2]) and as a hyperlink reference
(label).
This paragraph is pointed to by the explicit "example" target. A
reference can be found under Inline Markup, above. Inline
hyperlink targets are also possible.
Section headers are implicit targets, referred to by name. See
Targets, which is a subsection of Body Elements.
Explicit external targets are interpolated into references such as
"Python[5]".
Targets may be indirect and anonymous. Thus this phrase may also
refer to the Targets section.
Duplicate names in section headers or other implicit targets will
generate "info" (level-1) system messages. Duplicate names in
explicit targets will generate "warning" (level-2) system messages.
Since there are two "Duplicate Target Names" section headers, we
cannot uniquely refer to either of them by name. If we try to (like
this: `Duplicate Target Names`_), an error is generated.
An example of the "contents" directive can be seen above this section
(a local, untitled table of contents) and at the beginning of the
document (a document-wide table of contents).
The text below contains links that look like "(quickref)". These
are relative links that point to the Quick reStructuredText user
reference. If these links don't work, please refer to the master
quick reference document.
Note
This document is an informal introduction to
reStructuredText. The What Next? section below has links to
further resources, including a formal reference.
From the outset, let me say that "Structured Text" is probably a bit
of a misnomer. It's more like "Relaxed Text" that uses certain
consistent patterns. These patterns are interpreted by a HTML
converter to produce "Very Structured Text" that can be used by a web
browser.
The most basic pattern recognised is a paragraph (quickref).
That's a chunk of text that is separated by blank lines (one is
enough). Paragraphs must have the same indentation -- that is, line
up at their left edge. Paragraphs that start indented will result in
indented quote paragraphs. For example:
This is a paragraph. It's quite
short.
This paragraph will result in an indented block of
text, typically used for quoting other text.
This is another one.
Results in:
This is a paragraph. It's quite
short.
This paragraph will result in an indented block of
text, typically used for quoting other text.
Inside paragraphs and other bodies of text, you may additionally mark
text for italics with "*italics*" or bold with
"**bold**". This is called "inline markup".
If you want something to appear as a fixed-space literal, use
"``double back-quotes``". Note that no further fiddling is done
inside the double back-quotes -- so asterisks "*" etc. are left
alone.
If you find that you want to use one of the "special" characters in
text, it will generally be OK -- reStructuredText is pretty smart.
For example, this lone asterisk * is handled just fine, as is the
asterisk in this equation: 5*6=30. If you actually
want text *surrounded by asterisks* to not be italicised, then
you need to indicate that the asterisk is not special. You do this by
placing a backslash just before it, like so "\*" (quickref), or
by enclosing it in double back-quotes (inline literals), like this:
``*``
Tip
Think of inline markup as a form of (parentheses) and use it
the same way: immediately before and after the text being marked
up. Inline markup by itself (surrounded by whitespace) or in the
middle of a word won't be recognized. See the markup spec for
full details.
Lists of items come in three main flavours: enumerated,
bulleted and definitions. In all list cases, you may have as
many paragraphs, sublists, etc. as you want, as long as the left-hand
side of the paragraph or whatever aligns with the first line of text
in the list item.
Lists must always start a new paragraph -- that is, they must appear
after a blank line.
enumerated lists (numbers, letters or roman numerals; quickref)
Start a line off with a number or letter followed by a period ".",
right bracket ")" or surrounded by brackets "( )" -- whatever you're
comfortable with. All of the following forms are recognised:
1. numbers
A. upper-case letters
and it goes over many lines
with two paragraphs and all!
a. lower-case letters
3. with a sub-list starting at a different number
4. make sure the numbers are in the correct sequence though!
I. upper-case roman numerals
i. lower-case roman numerals
(1) numbers again
1) and again
Results in (note: the different enumerated list styles are not
always supported by every web browser, so you may not get the full
effect here):
numbers
upper-case letters
and it goes over many lines
with two paragraphs and all!
lower-case letters
with a sub-list starting at a different number
make sure the numbers are in the correct sequence though!
Unlike the other two, the definition lists consist of a term, and
the definition of that term. The format of a definition list is:
what
Definition lists associate a term with a definition.
*how*
The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.
Results in:
what
Definition lists associate a term with a definition.
how
The term is a one-line phrase, and the definition is one or more
paragraphs or body elements, indented relative to the term.
Blank lines are not allowed between term and definition.
To just include a chunk of preformatted, never-to-be-fiddled-with
text, finish the prior paragraph with "::". The preformatted
block is finished when the text falls back to the same indentation
level as a paragraph prior to the preformatted block. For example:
An example::
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
Results in:
An example:
Whitespace, newlines, blank lines, and all kinds of markup
(like *this* or \this) is preserved by literal blocks.
Lookie here, I've dropped an indentation level
(but not far enough)
no more example
Note that if a paragraph consists only of "::", then it's removed
from the output:
::
This is preformatted text, and the
last "::" paragraph is removed
Results in:
This is preformatted text, and the
last "::" paragraph is removed
To break longer text up into sections, you use section headers.
These are a single line of text (one or more words) with adornment: an
underline alone, or an underline and an overline together, in dashes
"-----", equals "======", tildes "~~~~~~" or any of the
non-alphanumeric characters = - ` : ' " ~ ^ _ * + # < > that you
feel comfortable with. An underline-only adornment is distinct from
an overline-and-underline adornment using the same character. The
underline/overline must be at least as long as the title text. Be
consistent, since all sections marked with the same adornment style
are deemed to be at the same level:
Chapter 1 Title
===============
Section 1.1 Title
-----------------
Subsection 1.1.1 Title
~~~~~~~~~~~~~~~~~~~~~~
Section 1.2 Title
-----------------
Chapter 2 Title
===============
This results in the following structure, illustrated by simplified
pseudo-XML:
<section>
<title>
Chapter 1 Title
<section>
<title>
Section 1.1 Title
<section>
<title>
Subsection 1.1.1 Title
<section>
<title>
Section 1.2 Title
<section>
<title>
Chapter 2 Title
(Pseudo-XML uses indentation for nesting and has no end-tags. It's
not possible to show actual processed output, as in the other
examples, because sections cannot exist inside block quotes. For a
concrete example, compare the section structure of this document's
source text and processed output.)
Note that section headers are available as link targets, just using
their name. To link to the Lists heading, I write "Lists_". If
the heading has a space in it like text styles, we need to quote
the heading "`text styles`_".
The title of the whole document is distinct from section titles and
may be formatted somewhat differently (e.g. the HTML writer by default
shows it as a centered heading).
To indicate the document title in reStructuredText, use a unique adornment
style at the beginning of the document. To indicate the document subtitle,
use another unique adornment style immediately after the document title. For
example:
================
Document Title
================
----------
Subtitle
----------
Section Title
=============
...
Note that "Document Title" and "Section Title" above both use equals
signs, but are distict and unrelated styles. The text of
overline-and-underlined titles (but not underlined-only) may be inset
for aesthetics.
To include an image in your document, you use the the imagedirective.
For example:
.. image:: images/biohazard.png
results in:
The images/biohazard.png part indicates the filename of the image
you wish to appear in the document. There's no restriction placed on
the image (format, size etc). If the image is to appear in HTML and
you wish to supply additional information, you may:
This primer introduces the most common features of reStructuredText,
but there are a lot more to explore. The Quick reStructuredText
user reference is a good place to go next. For complete details, the
reStructuredText Markup Specification is the place to go [1].
Users who have questions or need assistance with Docutils or
reStructuredText should post a message to the Docutils-users mailing
list.
