f | .. highlightlang:: rest |
| |
| reStructuredText Primer |
| ======================= |
| |
| This section is a brief introduction to reStructuredText (reST) concepts and |
n | syntax, intended to provide authors with enough information to author |
n | syntax, intended to provide authors with enough information to author documents |
| documents productively. |
| Since reST was designed to be a simple, unobtrusive markup language, this will |
| productively. Since reST was designed to be a simple, unobtrusive markup |
| not take too long. |
| language, this will not take too long. |
| |
| .. seealso:: |
| |
| The authoritative `reStructuredText User |
| Documentation <http://docutils.sourceforge.net/rst.html>`_. |
| |
| |
| Paragraphs |
| ---------- |
| |
n | The paragraph is the most basic block in a reST document. |
n | The paragraph is the most basic block in a reST document. Paragraphs are simply |
| Paragraphs are simply chunks of text |
| separated by one or more blank lines. As in Python, indentation is significant |
| chunks of text separated by one or more blank lines. As in Python, indentation |
| in reST, so all lines of the same paragraph must be left-aligned |
| is significant in reST, so all lines of the same paragraph must be left-aligned |
| to the same level of indentation. |
| |
| |
| Inline markup |
| ------------- |
| |
| The standard reST inline markup is quite simple: use |
| |
| List markup 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. |
| |
n | 1. This is a numbered list. |
| 2. It has two items too. |
| |
| #. This is a numbered list. |
| #. It has two items too. |
| |
n | |
| 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 |
| Paragraphs are quoted by just indenting them more than the surrounding |
| paragraphs. |
| |
| |
| Source Code |
| ----------- |
| |
| Literal code blocks are introduced by ending a paragraph with the special marker |
n | ``::``. The literal block must be indented, to be able to include blank lines:: |
n | ``::``. The literal block must be indented:: |
| |
| 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. |
| |
| |
| Lorem ipsum [#]_ dolor sit amet ... [#]_ |
| |
| .. rubric:: Footnotes |
| |
| .. [#] Text of the first footnote. |
| .. [#] Text of the second footnote. |
| |
n | You can also explicitly number the footnotes for better context. |
| |
| |
| Comments |
| -------- |
| |
| Every explicit markup block which isn't a valid markup construct (like the |
n | footnotes above) is regared as a comment. |
n | footnotes above) is regarded as a comment. |
| |
| |
| Source encoding |
| --------------- |
| |
| Since the easiest way to include special characters like em dashes or copyright |
| signs in reST is to directly write them as Unicode characters, one has to |
| specify an encoding: |
| |
| All Python documentation source files must be in UTF-8 encoding, and the HTML |
| documents written from them will be in that encoding as well. |
| |
| |
t | XXX: Gotchas |
t | Gotchas |
| ------- |
| |
| There are some problems one commonly runs into while authoring reST documents: |
| |
| * **Separation of inline markup:** As said above, inline markup spans must be |
| separated from the surrounding text by non-word characters, you have to use |
| an escaped space to get around that. |