reStructuredText
  • reStructuredText is commonly abbreviated reST (and will be called thus for the rest of this tutorial).
  • reST is a plantext markup syntax.
  • Home page is http://docutils.sf.net/rst.html
  • reST is accepted markup for Python Enhancement Proposals (PEPs); more info in PEP 12 (http://www.python.org/peps/pep-0012.html).
  • Docutils (and thus reST) will most likely be added to the Python Standard Library at some point in the future (no ETA on this).
  • Docutils can currently process reST into HTML (using Docutils/tools/html.py), but can output to other formats if a writer is created for the format (such as LaTeX, etc.).
  • Tutorial gives *rough* regular expression (regex) representations; will not be discussed actively but are there if you can read regexes.
  • Gray-background sections are example plaintext (on the left) and the corresponding HTML output from Docutils (on the right).
 
Example text is **here**
Example text is here
Sections
  • To delineate a section of a document, you give it a title and either underline it or overline *and* underline it with any non-alphanumeric characters which must be repeated as long as the title's length, including any markup.
  • Regex representation (approx.): ^(([^\w\s\d]+)\n)?.+\n(\1|[^\w\s\d])+
  • Each time you change the character used or change whether a character is used just for underlining or both overline and underline a new depth is defined that lasts until a new section of the same or higher depth is encountered.
  • What depth a character or lining style is used for carries for the whole document.
  • Every section automatically creates an interal link target (links are discussed later) named the same as the section title.
 
Depth 1
=======

=======
Depth 2
=======
Since we changed how '=' was used we created a new section
depth.

*Depth 1*
=========
Notice that we underlined to include even the '*' markup
(discussed later).

Depth 1

Depth 2

Since we changed how '=' was used we created a new section depth.

Depth 1

Notice that we underlined to include even the '*' markup (discussed later).
Paragraphs
  • A paragraph is just like in writing; a group of sentences all left-aligned to the same column.
  • Paragraphs are separated by a newline.
  • Regex representation (approx.): \n(\s*.+)+
 
This is a paragraph.

So is this.
Notice that having this sentence left-aligned makes it still
a part of the second paragraph.

This is a paragraph.

So is this. Notice that having this sentence left-aligned makes it still a part of the second paragraph.
Ordered and Unordered Lists
  • Ordered lists are numbered while unordered lists are not.
  • Start each list with a newline above the first list item.
  • Each list item is a paragraph, thus the text for each item must be left-aligned the same.
  • Unordered lists have items delineated by '-', '*', or '+' followed by whitespace; a separating newline is optional between items.
  • Unordered list item regex representation (approx.): [-*+]\s+.+
  • Ordered lists have items delineated by either Arabic numerals (1), alphabetic characters (A, a), or Roman Numerals (I or i) and are either followed by a period (1.), followed by a parenthesis (1)), or enclosed in parentheses ((1)).
  • Ordered list item regex representation (approx.): \([\w]\)|[\w]\)|[\w]\.
  • When changing how items are delineated, a new list is created.
  • When an item is led with more whitespace than the previous list item, a sub-list is created.
 
- An item.  Notice the whitespace between the '-' and "An".
- Another item.
  Notice that this line does not start a new item since it
  is left-aligned with the text on the previous line.

1. Item 1
2. Item 2

(3) Item 1 of a new list!

   1) Item 1 of a sub-list.

I. Roman numeral item.
  • An item. Notice the whitespace between the '-' and "An".
  • Another item. Notice that this line does not start a new item since it is left-aligned with the text on the previous line.
  1. Item 1
  2. Item 2
  1. Item 1 of a new list!
  1. Item 1 of a sub-list.
  1. Roman numeral item.
Definition Lists
  • Definition lists connect something with a definition.
  • Definition lists have, at minimum, an item (which can be anything that is a single line) and a definition on the line following the item with leading whitespace.
  • An optional classifier for the item is allowed; you create this after the item with whitespace, ':', whitespace, and then your classifier.Definition list regex representation (approx.): .+(\s+:\s+.+)?\n\s+.+
 
Word
    Definition of the word.
Another word of a definition list : This is a classifier
    Definition of the word with the classifier.
Word
Definition of the word.
Another word of a definition list : This is a classifier
Definition of the word with the classifier.
Literal Block
  • When a chunk of text is meant to be processed (i.e., left alone), you want a literal block.
  • The block of text must be indented relative to the last paragraph that is not literal and must start and end in newlines.
  • Precede the leading newline for the block of text with '::'.
  • When the '::' is on its own line it does not show up in the output.
  • When the '::' is immediately preceded by text it turns into a ':' in the output.
  • When the '::' has whitespace immediately preceding it to separate it from text it does not show up in the output.
  • Regex representation (approx.): ::\n\n(\s+.+)+\n
 
This paragraph will be followed by a colon::

    Literal block of text.
    It will not be processed.

    Even line breaks are kept.

This line will have no colon ::

    Some more literal text.

::

   Since this text has a :: and a newline
   preceding it, it is a literal block.
   Also notice that the '::' did not cause
   anything; the text in a literal block is not
   processed.

This paragraph will be followed by a colon:

Literal block of text.
It will not be processed.

Even line breaks are kept.

This line will have no colon

Some more literal text.

Since this text has a :: and a newline
preceding it, it is a literal block.
Also notice that the '::' did not cause
anything; the text in a literal block is not
processed.
Inline Markup
  • 3 most common are emphasis, strong emphasis, and inline literals.
  • Emphasis is denoted by surrounding the text with asterisks (*).
  • Emphasis regex representation (approx.): \*[^*]+\*
  • Strong emphasis is denoted by surround the text with two asterisks on each side (**).
  • Strong emphasis regex representation: \*\*[^*]+\*\*
  • Inline literals are surrounded by two back-ticks on each side (``).
  • Inline literal regex representation (approx.): ``[^`]``
  • Do not consider these equivalent to italics and bold; output might be that but the true meaning is more generic!
  • Do not go overboard with the use of inline literals; it can make text hard to read (as Guido and Tim Peters will tell you =).
 
This is *emphasis*.

This is **strong emphasis**.

This is an ``inline literal``.

This is emphasis.

This is strong emphasis.

This is an inline literal.
Explicit Hyperlink Targets
  • Explicit hyperlinks have two parts; the label and the named target of the link.
  • Delineate the label of the link by surrounding it in back-ticks and ending it with an underscore (`label`_).
  • If there are no spaces in the label nor punctuation you can just end it in an underscore and leave off the back-ticks.
  • Label of link regex representation (approx.): [^\s]_|`.+`_
  • The target is done by starting with 2 '.', whitespace, an '_', the label of the link, a ':', and then whitespace (.. _label: ).
  • Targets are whitespace-neutral and case-insensitive.
  • Target of link regex representation (approx.): \.\.\w+_.+:\w+
  • Once a target is defined it is good for the whole document and can be placed at any point in the document.
  • Targets need to be separated by newlines from anything that is a not a target; targets themselves can be listed one after the other.
  • Redefining a target will lead to an error.
  • If a target has no address given it gets it from the following target, allowing chaining (for abbreviations and the long version, for instance).
 
This sentence has simple link_ in it.

.. _link: http://www.google.com./

This sentence has a `long link`_ in it.
This one has a link that has an address that's the `same as the long link`_ .

.. _same as the long link: 
.. _long link: http://makeashorterlink.com./

Remember, `link targets`_ are case-insensitive and whitespace-neutral.

.. _LINK   TARGETS: http://pythonowns.blogspot.com/

This sentence has simple link in it.

This sentence has a long link in it. This one has a link that has an address that's the same as the long link .

Remember, link targets are case-insensitive and whitespace-neutral.
Implicit Hyperlink Targets
  • Implicit hyperlinks do not need their targets named like explicit hyperlink targets.
  • Implicit hyperlinks come in two flavors, inline and non-inline.
  • A non-inline hyperlink label is marked like an explicit hyperlink's label except '__' is used instead of '-' (`label`__).
  • Non-inline hyperlink regex representation (approx.): [^\s]__|`.+`__
  • The target for non-inline implicit links are denoted by '..', whitespace, '__:', and whitespace (.. __: ); a shorthand is two underlines and whitespace (__ ).
  • Non-inline target regex representation (approx.): __\s+.+|\.\.\s+__:\s+.+
  • You do not need to have the target defined before the next anonymous link; they are resolved in order.
  • Inline implicit hyperlinks have the form `label <hyperlink>`__ .
  • Inline hyperlink regex representation (approx.): `.+\s+<.+>`__
  • Be weary of inlined links because they can become quite long.
  • When you have errors about having more links than targets, try to solve them by searching for `__ and checking that it is meant to be implicit and that if it is inline that the link was written in.
 
Here is an `implicit link`__ .

.. __:   http://www.python.org./

Shorthand target is used__ below.

__ http://www.kbb.com/

This link has an `inlined <http://www.python.org./>`__ link.

You do not need to have the link__ target before__ the next anonymous link.

__ http://www.w3.org./
__ http://www.archive.org/

Here is an implicit link .

Shorthand target is used below.

This link has an inlined link.

You do not need to have the link target before the next anonymous link.
Directives
  • Directives are a way to extend reST in a domain-specific ways.
  • Directives are '..', whitespace, a name, '::', and whitespace (.. directive:: ); they can have an optional argument listed afterwards.
  • regex representation (approx.): \.\.\w+.+::(\s+.+)?
  • There are several built-in directives that are guaranteed to be in the reST parser (can be found online in the docs).
  • PEP 12 (Sample reStructuredText PEP Template) specifically mentions the .. image:: directive for inserting an image.
  • The python-dev Summaries use the .. contents:: directive to create a table of contents listing all sections in the document.
  • .. note:: is just what is sounds like; its a note in the document.
 
.. note:: This is a note directive.

Note

This is a note directive.
Comments
  • Comments do not show up in the processed output.
  • Create one by '..' followed by whitespace; any indented text afterwards is also part of the comment.
  • Regex representation (approx.): ..\s+.+(\n\s+.+)*
 
.. This is a comment

..
    So is this.

.. A nice long comment...
    that continues on the next line.
Footnotes
  • Footnotes come in 3 flavors: numbered, auto-number, auto-number label, and auto-symbol.
  • Numbered footnotes are created by '[', a number, ']', then an underscore([1]_); the target is '..', whitespace, '[', the number, ']', whitespace, and then the address (.. [1] ).
  • Numbered footnote label regex representation (approx.): \[\d+\]_
  • Numbered footnoate target regex representation (approx.): \.\.\s+\[\d+\]\w+.+
  • Autonumbered footnotes are just like manual footnotes except instead of having to specify the number you just put a hash mark (#); numbers are inserted automatically.
  • Auto-numbered footnote label regex representation (approx.): \[#\]_
  • Auto-numbered footnote target regex representation (approx.): \.\.\s+\[#\]\w+.+
  • Auto-number labeled footnotes let you name the footnotes while they are replaced with numbers in the output; they are done with a hash mark followed by a label instead of the number ([#label]).
  • Auto-number labeled footnote label regex representation (approx.): \[#\w+\]_
  • Auto-number labeled footnote target regex representation (approx.): \.\.\s+\[#\w+\]\w+.+
  • Auto-symbol footnotes are created by using an asterisk in the brackets; output substitutes with a symbol pulled from rotating list.
  • Auto-symbol footnote label regex representation (approx.): \[\*\]_
  • Auto-symbol footnote target regex representation (approx.): \.\.\s+\[\*\]\w+.+
  • Targets for footnotes are outputted where they lay in the document; if you want all links at the end of your document then put the targets at the end of the document as well.
 
This is manual footnote 1 [1]_.
This is manual footnote 2 [2]_.

.. [1] http://www.python.org./
.. [2] http://www.parrotcode.org./

This is an auto-numbered footnote [#]_.

.. [#] http://www.perl.org./

This is an auto-numbered label footnote [#ruby]_.

.. [#ruby] http://www.ruby-lang.org/en/

This is an auto-symbol footnote [*]_.
And this is another auto-symbol [*]_.

.. [*] http://www.ocaml.org/
.. [*] http://www.swiss.ai.mit.edu/projects/scheme/

This is manual footnote 1 1. This is manual footnote 2 2.

[1]http://www.python.org./
[2]http://www.parrotcode.org./

This is an auto-numbered footnote 3.

[3]http://www.perl.org./

This is an auto-numbered label footnote 4.

[4]http://www.ruby-lang.org/en/

This is an auto-symbol footnote *. And this is another auto-symbol †.

[*]http://www.ocaml.org/
[†]http://www.swiss.ai.mit.edu/projects/scheme/