l4/pkg/python/contrib/Doc/documenting/rest.rst

   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
  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
 101 ``::``.  The literal block must be indented::
 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.