4.2. The reStructuredText Cheat Sheet¶
4.2.1. Section Structure¶
Section titles are underlined or overlined & underlined.
4.2.2. Body Elements¶
Grid table:
Paragraphs are flush-left, separated by blank lines.
|
Literal block, preceded by “::”: Indented
or: > Quoted
|
>>> print 'Doctest block'
Doctest block
|
|
Line blocks preserve line breaks & indents. [new in 0.3.6]
Useful for addresses, verse, and adornment-free lists; long
lines can be wrapped with continuation lines.
|
Simple tables:
List Type | Examples (syntax in the text source) | ||
---|---|---|---|
Bullet list |
|
||
Enumerated list |
|
||
Definition list |
|
||
Field list |
|
||
Option list |
|
Explicit Markup | Examples (visible in the text source) | ||
---|---|---|---|
Footnote |
|
||
Citation |
|
||
Hyperlink Target | |||
Anonymous Target | |||
Directive (“::”) | |||
Substitution Def | |||
Comment | |||
Empty Comment | (“..” on a line by itself, with blank lines before & after, used to separate indentation contexts) |
4.2.3. Inline Markup¶
- emphasis
- strong emphasis
- interpreted text
- interpreted text with role
inline literal text
- standalone hyperlink: http://docutils.sourceforge.net
- named reference: reStructuredText
- anonymous reference
- footnote reference: [1]
- citation reference: [CIT2002]
|substitution|
_`inline internal target`
4.2.4. Directive Quick Reference¶
See http://docutils.sf.net/docs/ref/rst/directives.html for full info.
Directive Name | Description (Docutils version added to, in [brackets]) |
---|---|
attention | Specific admonition; also “caution”, “danger”, “error”, “hint”, “important”, “note”, “tip”, “warning” |
admonition | Generic titled admonition: .. admonition:: By The Way |
image | .. image:: picture.png ; many options possible |
figure | Like “image”, but with optional caption and legend |
topic | .. topic:: Title ; like a mini section |
sidebar | .. sidebar:: Title ; like a mini parallel document |
parsed-literal | A literal block with parsed inline markup |
rubric | .. rubric:: Informal Heading |
epigraph | Block quote with class=”epigraph” |
highlights | Block quote with class=”highlights” |
pull-quote | Block quote with class=”pull-quote” |
compound | Compound paragraphs [0.3.6] |
container | Generic block-level container element [0.3.10] |
table | Create a titled table [0.3.1] |
list-table | Create a table from a uniform two-level bullet list [0.3.8] |
csv-table | Create a table from CSV data [0.3.4] |
contents | Generate a table of contents |
sectnum | Automatically number sections, subsections, etc. |
header, footer | Create document decorations [0.3.8] |
target-notes | Create an explicit footnote for each external target |
math | Mathematical notation (input in LaTeX format) |
meta | HTML-specific metadata |
include | Read an external reST file as if it were inline |
raw | Non-reST data passed untouched to the Writer |
replace | Replacement text for substitution definitions |
unicode | Unicode character code conversion for substitution defs |
date | Generates today’s date; for substitution defs |
class | Set a “class” attribute on the next element |
role | Create a custom interpreted text role [0.3.2] |
default-role | Set the default interpreted text role [0.3.10] |
title | Set the metadata document title [0.3.10] |
4.2.5. Interpreted Text Role Quick Reference¶
See http://docutils.sf.net/docs/ref/rst/roles.html for full info.
Role Name | Description |
---|---|
emphasis | Equivalent to emphasis |
literal | Equivalent to literal but processes backslash escapes |
math | Mathematical notation (input in LaTeX format) |
PEP | Reference to a numbered Python Enhancement Proposal |
RFC | Reference to a numbered Internet Request For Comments |
raw | For non-reST data; cannot be used directly (see docs) [0.3.6] |
strong | Equivalent to strong |
sub | Subscript |
sup | Superscript |
title | Title reference (book, etc.); standard default role |