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
$Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $
status
This is a "work in progress"
revision
$Revision: 7302 $
version
1
copyright
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.
Table of Contents
Structural Elements
Section Title
That's it, the text just above this line.
Transitions
Here's a transition:
It divides the section.
Body Elements
Paragraphs
A paragraph.
Inline Markup
Paragraphs contain text and may contain inline markup: emphasis, strong emphasis, inline literals, standalone hyperlinks (http://www.python.org), external hyperlinks (Python), internal cross-references (example), external hyperlinks with embedded URIs (Python web site), footnote references (manually numbered1, anonymous auto-numbered2, labeled auto-numbered3, or symbolic4), 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 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.
Bullet Lists
A bullet list
Nested bullet list.
Nested item 2.
Item 2.
Paragraph 2 of item 2.
Nested bullet list.
Nested item 2.
Third level.
Item 2.
Nested item 3.
Enumerated Lists
Arabic numerals.
lower alpha)
(lower roman)
upper alpha.
upper roman)
Lists that don't start at 1:
Three
Four
C
D
iii
iv
List items may also be auto-enumerated.
Definition Lists
Term
Definition
Term : classifier
Definition paragraph 1.
Definition paragraph 2.
Term
Definition
Field Lists
what
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.
Option Lists
For listing command-line options:
-a command-line option "a" -b file options can have arguments and long descriptions --long options can be long also --input=file long options can also have arguments
--very-long-option
The description can also start on the next line.
The description may contain multiple body elements, regardless of where it starts.
-x, -y, -z Multiple options are an "option group". -v, --verbose Commonly-seen: short & long options. -1 file, --one=file, --two file Multiple options with arguments. /V DOS/VMS-style options too
There must be at least two spaces between the option and the description.
Literal Blocks
Literal blocks are indicated with a double-colon ("::") at the end of the preceding paragraph (over there -->). They can be indented:
if literal_block:
text = 'is left as-is'
spaces_and_linebreaks = 'are preserved'
markup_processing = None
Or they can be quoted without indentation:
>> Great idea!
>
> Why didn't I think of that?
Line Blocks
This is a line block. It ends with a blank line.
Each new line begins with a vertical bar ("|").
Line breaks and initial indents are preserved.
Continuation lines are wrapped portions of long lines; they begin with a space in place of the vertical bar.
The left edge of a continuation line need not be aligned with the left edge of the text above it.
This is a second line block.
Blank lines are permitted internally, but they must begin with a "|".
Take it away, Eric the Orchestra Leader!
A one, two, a one two three four
Half a bee, philosophically,
must, ipso facto, half not be.
But half the bee has got to be,
*vis a vis* its entity. D'you see?
But can a bee be said to be
or not to be an entire bee,
when half the bee is not a bee,
due to some ancient injury?
Singing...
Block Quotes
Block quotes consist of indented body elements:
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.
-- Anne Elk (Miss)
Doctest Blocks
>>> 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)
Tables
Here's a grid table followed by a simple table:
+------------------------+------------+----------+----------+ | 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 | Cells may span columns. | +------------------------+------------+---------------------+ | body row 3 | Cells may | - Table cells | +------------------------+ span rows. | - contain | | body row 4 | | - body elements. | +------------------------+------------+----------+----------+ | body row 5 | Cells may also be | | | | empty: --> | | +------------------------+-----------------------+----------+
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".
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.
Duplicate Target Names
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).
Images
An image directive (also clickable -- a hyperlink reference):
A figure directive:
A figure is an image with a caption and/or a legend:
re
Revised, revisited, based on 're' module.
Structured
Structure-enhanced text, structuredtext.
Text
Well it is, isn't it?
This paragraph is also part of the legend.
Admonitions
Attention
Directives at large.
Caution
Don't take any wooden nickels.
Danger
Mad scientist at work!
Error
Does not compute.
Hint
It's bigger than a bread box.
Important
- Wash behind your ears. - Clean up your room. - Call your mother. - Back up your data.
Note
This is a note.
Tip
15% if the service is good.
Warning
Strong prose may provoke extreme mental exertion. Reader discretion is strongly advised.
And, by the way...
You can make up your own admonition too.
Topics, Sidebars, and Rubrics
Sidebar Title: Optional Subtitle
This is a sidebar. It is for text outside the flow of the main text.
This is a rubric inside a sidebar
Sidebars often appears beside the main text with a border and background color.
Topic Title
This is a topic.
This is a rubric
Target Footnotes
Replacement Text
I recommend you try Python, the best language around_.
Compound Paragraph
This paragraph contains a literal block:
Connecting... OK
Transmitting data... OK
Disconnecting... OK
and thus consists of a simple paragraph, a literal block, and another simple paragraph. Nonetheless it is semantically one paragraph.
This construct is called a compound paragraph and can be produced with the "compound" directive.
Substitution Definitions
An inline image () example:
(Substitution definitions are not visible in the HTML source.)
Comments
Here's one:
(View the HTML source to see the comment.)
Error Handling
Any errors caught during processing will generate system messages.
There should be six messages in the following, auto-generated section, "Docutils System Messages":
CIT2002
Citations are text-labeled footnotes. They may be rendered separately and differently from footnotes.
A footnote contains body elements, consistently indented by at least 3 spaces.
This footnote is numbered automatically and anonymously using a label of "#" only.↩
Footnotes may be numbered, either manually (as in) 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 () and as a hyperlink reference (label).↩
Footnotes may also use symbols, specified with a "" label. Here's a reference to the next footnote: []_.↩
This document has been placed in the public domain.
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.
Structure
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
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)
__ quickref.html#enumerated-lists
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`_".
Document Title / Subtitle
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.
Images
(quickref__)
To include an image in your document, you use the the image directive__. 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:
See the full image directive documentation__ for more info.
What Next?
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 go1.
Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-users mailing list.
