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 Note that Sphinx disables the use of enumerated lists introduced by alphabetic

    71 or roman numerals, such as ::

    72 

    73    A. First item

    74    B. Second item

    75    

    76 

    77 Nested lists are possible, but be aware that they must be separated from the

    78 parent list items by blank lines::

    79 

    80    * this is

    81    * a list

    82 

    83      * with a nested list

    84      * and some subitems

    85 

    86    * and here the parent list continues

    87 

    88 Definition lists are created as follows::

    89 

    90    term (up to a line of text)

    91       Definition of the term, which must be indented

    92 

    93       and can even consist of multiple paragraphs

    94 

    95    next term

    96       Description.

    97 

    98 

    99 Paragraphs are quoted by just indenting them more than the surrounding

   100 paragraphs.

   101 

   102 

   103 Source Code

   104 -----------

   105 

   106 Literal code blocks are introduced by ending a paragraph with the special marker

   107 ``::``.  The literal block must be indented, to be able to include blank lines::

   108 

   109    This is a normal text paragraph. The next paragraph is a code sample::

   110 

   111       It is not processed in any way, except

   112       that the indentation is removed.

   113 

   114       It can span multiple lines.

   115 

   116    This is a normal text paragraph again.

   117 

   118 The handling of the ``::`` marker is smart:

   119 

   120 * If it occurs as a paragraph of its own, that paragraph is completely left

   121   out of the document.

   122 * If it is preceded by whitespace, the marker is removed.

   123 * If it is preceded by non-whitespace, the marker is replaced by a single

   124   colon.

   125 

   126 That way, the second sentence in the above example's first paragraph would be

   127 rendered as "The next paragraph is a code sample:".

   128 

   129 

   130 Hyperlinks

   131 ----------

   132 

   133 External links

   134 ^^^^^^^^^^^^^^

   135 

   136 Use ```Link text <http://target>`_`` for inline web links.  If the link text

   137 should be the web address, you don't need special markup at all, the parser

   138 finds links and mail addresses in ordinary text.

   139 

   140 Internal links

   141 ^^^^^^^^^^^^^^

   142 

   143 Internal linking is done via a special reST role, see the section on specific

   144 markup, :ref:`doc-ref-role`.

   145 

   146 

   147 Sections

   148 --------

   149 

   150 Section headers are created by underlining (and optionally overlining) the

   151 section title with a punctuation character, at least as long as the text::

   152 

   153    =================

   154    This is a heading

   155    =================

   156 

   157 Normally, there are no heading levels assigned to certain characters as the

   158 structure is determined from the succession of headings.  However, for the

   159 Python documentation, we use this convention:

   160 

   161 * ``#`` with overline, for parts

   162 * ``*`` with overline, for chapters

   163 * ``=``, for sections

   164 * ``-``, for subsections

   165 * ``^``, for subsubsections

   166 * ``"``, for paragraphs

   167 

   168 

   169 Explicit Markup

   170 ---------------

   171 

   172 "Explicit markup" is used in reST for most constructs that need special

   173 handling, such as footnotes, specially-highlighted paragraphs, comments, and

   174 generic directives.

   175 

   176 An explicit markup block begins with a line starting with ``..`` followed by

   177 whitespace and is terminated by the next paragraph at the same level of

   178 indentation.  (There needs to be a blank line between explicit markup and normal

   179 paragraphs.  This may all sound a bit complicated, but it is intuitive enough

   180 when you write it.)

   181 

   182 

   183 Directives

   184 ----------

   185 

   186 A directive is a generic block of explicit markup.  Besides roles, it is one of

   187 the extension mechanisms of reST, and Sphinx makes heavy use of it.

   188 

   189 Basically, a directive consists of a name, arguments, options and content. (Keep

   190 this terminology in mind, it is used in the next chapter describing custom

   191 directives.)  Looking at this example, ::

   192 

   193    .. function:: foo(x)

   194                  foo(y, z)

   195       :bar: no

   196 

   197       Return a line of text input from the user.

   198 

   199 ``function`` is the directive name.  It is given two arguments here, the

   200 remainder of the first line and the second line, as well as one option ``bar``

   201 (as you can see, options are given in the lines immediately following the

   202 arguments and indicated by the colons).

   203 

   204 The directive content follows after a blank line and is indented relative to the

   205 directive start.

   206 

   207 

   208 Footnotes

   209 ---------

   210 

   211 For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote

   212 body at the bottom of the document after a "Footnotes" rubric heading, like so::

   213 

   214    Lorem ipsum [#]_ dolor sit amet ... [#]_

   215 

   216    .. rubric:: Footnotes

   217 

   218    .. [#] Text of the first footnote.

   219    .. [#] Text of the second footnote.

   220 

   221 You can also explicitly number the footnotes for better context.

   222 

   223 

   224 Comments

   225 --------

   226 

   227 Every explicit markup block which isn't a valid markup construct (like the

   228 footnotes above) is regarded as a comment.

   229 

   230 

   231 Source encoding

   232 ---------------

   233 

   234 Since the easiest way to include special characters like em dashes or copyright

   235 signs in reST is to directly write them as Unicode characters, one has to

   236 specify an encoding:

   237 

   238 All Python documentation source files must be in UTF-8 encoding, and the HTML

   239 documents written from them will be in that encoding as well.

   240 

   241 

   242 Gotchas

   243 -------

   244 

   245 There are some problems one commonly runs into while authoring reST documents:

   246 

   247 * **Separation of inline markup:** As said above, inline markup spans must be

   248   separated from the surrounding text by non-word characters, you have to use

   249   an escaped space to get around that.

   250 

   251 .. XXX more?