Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | .. highlightlang:: rest |
| 2 | |
| 3 | reStructuredText Primer |
| 4 | ======================= |
| 5 | |
| 6 | This section is a brief introduction to reStructuredText (reST) concepts and |
| 7 | syntax, intended to provide authors with enough information to author documents |
| 8 | productively. Since reST was designed to be a simple, unobtrusive markup |
| 9 | language, this will not take too long. |
| 10 | |
| 11 | .. seealso:: |
| 12 | |
| 13 | The authoritative `reStructuredText User |
| 14 | Documentation <http://docutils.sourceforge.net/rst.html>`_. |
| 15 | |
| 16 | |
| 17 | Paragraphs |
| 18 | ---------- |
| 19 | |
| 20 | The paragraph is the most basic block in a reST document. Paragraphs are simply |
| 21 | chunks of text separated by one or more blank lines. As in Python, indentation |
| 22 | is significant in reST, so all lines of the same paragraph must be left-aligned |
| 23 | to the same level of indentation. |
| 24 | |
| 25 | |
| 26 | Inline markup |
| 27 | ------------- |
| 28 | |
| 29 | The standard reST inline markup is quite simple: use |
| 30 | |
| 31 | * one asterisk: ``*text*`` for emphasis (italics), |
| 32 | * two asterisks: ``**text**`` for strong emphasis (boldface), and |
| 33 | * backquotes: ````text```` for code samples. |
| 34 | |
| 35 | If asterisks or backquotes appear in running text and could be confused with |
| 36 | inline markup delimiters, they have to be escaped with a backslash. |
| 37 | |
| 38 | Be aware of some restrictions of this markup: |
| 39 | |
| 40 | * it may not be nested, |
| 41 | * content may not start or end with whitespace: ``* text*`` is wrong, |
| 42 | * it must be separated from surrounding text by non-word characters. Use a |
| 43 | backslash escaped space to work around that: ``thisis\ *one*\ word``. |
| 44 | |
| 45 | These restrictions may be lifted in future versions of the docutils. |
| 46 | |
| 47 | reST also allows for custom "interpreted text roles"', which signify that the |
| 48 | enclosed text should be interpreted in a specific way. Sphinx uses this to |
| 49 | provide semantic markup and cross-referencing of identifiers, as described in |
| 50 | the appropriate section. The general syntax is ``:rolename:`content```. |
| 51 | |
| 52 | |
| 53 | Lists and Quotes |
| 54 | ---------------- |
| 55 | |
| 56 | List markup is natural: just place an asterisk at the start of a paragraph and |
| 57 | indent properly. The same goes for numbered lists; they can also be |
| 58 | autonumbered using a ``#`` sign:: |
| 59 | |
| 60 | * This is a bulleted list. |
| 61 | * It has two items, the second |
| 62 | item uses two lines. |
| 63 | |
| 64 | 1. This is a numbered list. |
| 65 | 2. It has two items too. |
| 66 | |
| 67 | #. This is a numbered list. |
| 68 | #. It has two items too. |
| 69 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
| 71 | Nested lists are possible, but be aware that they must be separated from the |
| 72 | parent list items by blank lines:: |
| 73 | |
| 74 | * this is |
| 75 | * a list |
| 76 | |
| 77 | * with a nested list |
| 78 | * and some subitems |
| 79 | |
| 80 | * and here the parent list continues |
| 81 | |
| 82 | Definition lists are created as follows:: |
| 83 | |
| 84 | term (up to a line of text) |
| 85 | Definition of the term, which must be indented |
| 86 | |
| 87 | and can even consist of multiple paragraphs |
| 88 | |
| 89 | next term |
| 90 | Description. |
| 91 | |
| 92 | |
| 93 | Paragraphs are quoted by just indenting them more than the surrounding |
| 94 | paragraphs. |
| 95 | |
| 96 | |
| 97 | Source Code |
| 98 | ----------- |
| 99 | |
| 100 | Literal code blocks are introduced by ending a paragraph with the special marker |
Georg Brandl | af265f4 | 2008-12-07 15:06:20 +0000 | [diff] [blame] | 101 | ``::``. The literal block must be indented:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 102 | |
| 103 | This is a normal text paragraph. The next paragraph is a code sample:: |
| 104 | |
| 105 | It is not processed in any way, except |
| 106 | that the indentation is removed. |
| 107 | |
| 108 | It can span multiple lines. |
| 109 | |
| 110 | This is a normal text paragraph again. |
| 111 | |
| 112 | The handling of the ``::`` marker is smart: |
| 113 | |
| 114 | * If it occurs as a paragraph of its own, that paragraph is completely left |
| 115 | out of the document. |
| 116 | * If it is preceded by whitespace, the marker is removed. |
| 117 | * If it is preceded by non-whitespace, the marker is replaced by a single |
| 118 | colon. |
| 119 | |
| 120 | That way, the second sentence in the above example's first paragraph would be |
| 121 | rendered as "The next paragraph is a code sample:". |
| 122 | |
| 123 | |
| 124 | Hyperlinks |
| 125 | ---------- |
| 126 | |
| 127 | External links |
| 128 | ^^^^^^^^^^^^^^ |
| 129 | |
| 130 | Use ```Link text <http://target>`_`` for inline web links. If the link text |
| 131 | should be the web address, you don't need special markup at all, the parser |
| 132 | finds links and mail addresses in ordinary text. |
| 133 | |
| 134 | Internal links |
| 135 | ^^^^^^^^^^^^^^ |
| 136 | |
| 137 | Internal linking is done via a special reST role, see the section on specific |
| 138 | markup, :ref:`doc-ref-role`. |
| 139 | |
| 140 | |
| 141 | Sections |
| 142 | -------- |
| 143 | |
| 144 | Section headers are created by underlining (and optionally overlining) the |
| 145 | section title with a punctuation character, at least as long as the text:: |
| 146 | |
| 147 | ================= |
| 148 | This is a heading |
| 149 | ================= |
| 150 | |
| 151 | Normally, there are no heading levels assigned to certain characters as the |
| 152 | structure is determined from the succession of headings. However, for the |
| 153 | Python documentation, we use this convention: |
| 154 | |
| 155 | * ``#`` with overline, for parts |
| 156 | * ``*`` with overline, for chapters |
| 157 | * ``=``, for sections |
| 158 | * ``-``, for subsections |
| 159 | * ``^``, for subsubsections |
| 160 | * ``"``, for paragraphs |
| 161 | |
| 162 | |
| 163 | Explicit Markup |
| 164 | --------------- |
| 165 | |
| 166 | "Explicit markup" is used in reST for most constructs that need special |
| 167 | handling, such as footnotes, specially-highlighted paragraphs, comments, and |
| 168 | generic directives. |
| 169 | |
| 170 | An explicit markup block begins with a line starting with ``..`` followed by |
| 171 | whitespace and is terminated by the next paragraph at the same level of |
| 172 | indentation. (There needs to be a blank line between explicit markup and normal |
| 173 | paragraphs. This may all sound a bit complicated, but it is intuitive enough |
| 174 | when you write it.) |
| 175 | |
| 176 | |
| 177 | Directives |
| 178 | ---------- |
| 179 | |
| 180 | A directive is a generic block of explicit markup. Besides roles, it is one of |
| 181 | the extension mechanisms of reST, and Sphinx makes heavy use of it. |
| 182 | |
| 183 | Basically, a directive consists of a name, arguments, options and content. (Keep |
| 184 | this terminology in mind, it is used in the next chapter describing custom |
| 185 | directives.) Looking at this example, :: |
| 186 | |
| 187 | .. function:: foo(x) |
| 188 | foo(y, z) |
| 189 | :bar: no |
| 190 | |
| 191 | Return a line of text input from the user. |
| 192 | |
| 193 | ``function`` is the directive name. It is given two arguments here, the |
| 194 | remainder of the first line and the second line, as well as one option ``bar`` |
| 195 | (as you can see, options are given in the lines immediately following the |
| 196 | arguments and indicated by the colons). |
| 197 | |
| 198 | The directive content follows after a blank line and is indented relative to the |
| 199 | directive start. |
| 200 | |
| 201 | |
| 202 | Footnotes |
| 203 | --------- |
| 204 | |
| 205 | For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote |
| 206 | body at the bottom of the document after a "Footnotes" rubric heading, like so:: |
| 207 | |
| 208 | Lorem ipsum [#]_ dolor sit amet ... [#]_ |
| 209 | |
| 210 | .. rubric:: Footnotes |
| 211 | |
| 212 | .. [#] Text of the first footnote. |
| 213 | .. [#] Text of the second footnote. |
| 214 | |
| 215 | You can also explicitly number the footnotes for better context. |
| 216 | |
| 217 | |
| 218 | Comments |
| 219 | -------- |
| 220 | |
| 221 | Every explicit markup block which isn't a valid markup construct (like the |
| 222 | footnotes above) is regarded as a comment. |
| 223 | |
| 224 | |
| 225 | Source encoding |
| 226 | --------------- |
| 227 | |
| 228 | Since the easiest way to include special characters like em dashes or copyright |
| 229 | signs in reST is to directly write them as Unicode characters, one has to |
| 230 | specify an encoding: |
| 231 | |
| 232 | All Python documentation source files must be in UTF-8 encoding, and the HTML |
| 233 | documents written from them will be in that encoding as well. |
| 234 | |
| 235 | |
| 236 | Gotchas |
| 237 | ------- |
| 238 | |
| 239 | There are some problems one commonly runs into while authoring reST documents: |
| 240 | |
| 241 | * **Separation of inline markup:** As said above, inline markup spans must be |
| 242 | separated from the surrounding text by non-word characters, you have to use |
| 243 | an escaped space to get around that. |