244 lines
7.0 KiB
ReStructuredText
244 lines
7.0 KiB
ReStructuredText
.. highlightlang:: rest
|
|
|
|
reStructuredText Primer
|
|
=======================
|
|
|
|
This section is a brief introduction to reStructuredText (reST) concepts and
|
|
syntax, intended to provide authors with enough information to author documents
|
|
productively. Since reST was designed to be a simple, unobtrusive markup
|
|
language, this will not take too long.
|
|
|
|
.. seealso::
|
|
|
|
The authoritative `reStructuredText User
|
|
Documentation <http://docutils.sourceforge.net/rst.html>`_.
|
|
|
|
|
|
Paragraphs
|
|
----------
|
|
|
|
The paragraph is the most basic block in a reST document. Paragraphs are simply
|
|
chunks of text separated by one or more blank lines. As in Python, indentation
|
|
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
|
|
|
|
* one asterisk: ``*text*`` for emphasis (italics),
|
|
* two asterisks: ``**text**`` for strong emphasis (boldface), and
|
|
* backquotes: ````text```` for code samples.
|
|
|
|
If asterisks or backquotes appear in running text and could be confused with
|
|
inline markup delimiters, they have to be escaped with a backslash.
|
|
|
|
Be aware of some restrictions of this markup:
|
|
|
|
* it may not be nested,
|
|
* content may not start or end with whitespace: ``* text*`` is wrong,
|
|
* it must be separated from surrounding text by non-word characters. Use a
|
|
backslash escaped space to work around that: ``thisis\ *one*\ word``.
|
|
|
|
These restrictions may be lifted in future versions of the docutils.
|
|
|
|
reST also allows for custom "interpreted text roles"', which signify that the
|
|
enclosed text should be interpreted in a specific way. Sphinx uses this to
|
|
provide semantic markup and cross-referencing of identifiers, as described in
|
|
the appropriate section. The general syntax is ``:rolename:`content```.
|
|
|
|
|
|
Lists and Quotes
|
|
----------------
|
|
|
|
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.
|
|
|
|
1. This is a numbered list.
|
|
2. It has two items too.
|
|
|
|
#. This is a numbered list.
|
|
#. It has two items too.
|
|
|
|
|
|
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
|
|
|
|
* and here the parent list continues
|
|
|
|
Definition lists are created as follows::
|
|
|
|
term (up to a line of text)
|
|
Definition of the term, which must be indented
|
|
|
|
and can even consist of multiple paragraphs
|
|
|
|
next term
|
|
Description.
|
|
|
|
|
|
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
|
|
``::``. 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.
|
|
|
|
This is a normal text paragraph again.
|
|
|
|
The handling of the ``::`` marker is smart:
|
|
|
|
* If it occurs as a paragraph of its own, that paragraph is completely left
|
|
out of the document.
|
|
* If it is preceded by whitespace, the marker is removed.
|
|
* If it is preceded by non-whitespace, the marker is replaced by a single
|
|
colon.
|
|
|
|
That way, the second sentence in the above example's first paragraph would be
|
|
rendered as "The next paragraph is a code sample:".
|
|
|
|
|
|
Hyperlinks
|
|
----------
|
|
|
|
External links
|
|
^^^^^^^^^^^^^^
|
|
|
|
Use ```Link text <http://target>`_`` for inline web links. If the link text
|
|
should be the web address, you don't need special markup at all, the parser
|
|
finds links and mail addresses in ordinary text.
|
|
|
|
Internal links
|
|
^^^^^^^^^^^^^^
|
|
|
|
Internal linking is done via a special reST role, see the section on specific
|
|
markup, :ref:`doc-ref-role`.
|
|
|
|
|
|
Sections
|
|
--------
|
|
|
|
Section headers are created by underlining (and optionally overlining) the
|
|
section title with a punctuation character, at least as long as the text::
|
|
|
|
=================
|
|
This is a heading
|
|
=================
|
|
|
|
Normally, there are no heading levels assigned to certain characters as the
|
|
structure is determined from the succession of headings. However, for the
|
|
Python documentation, we use this convention:
|
|
|
|
* ``#`` with overline, for parts
|
|
* ``*`` with overline, for chapters
|
|
* ``=``, for sections
|
|
* ``-``, for subsections
|
|
* ``^``, for subsubsections
|
|
* ``"``, for paragraphs
|
|
|
|
|
|
Explicit Markup
|
|
---------------
|
|
|
|
"Explicit markup" is used in reST for most constructs that need special
|
|
handling, such as footnotes, specially-highlighted paragraphs, comments, and
|
|
generic directives.
|
|
|
|
An explicit markup block begins with a line starting with ``..`` followed by
|
|
whitespace and is terminated by the next paragraph at the same level of
|
|
indentation. (There needs to be a blank line between explicit markup and normal
|
|
paragraphs. This may all sound a bit complicated, but it is intuitive enough
|
|
when you write it.)
|
|
|
|
|
|
Directives
|
|
----------
|
|
|
|
A directive is a generic block of explicit markup. Besides roles, it is one of
|
|
the extension mechanisms of reST, and Sphinx makes heavy use of it.
|
|
|
|
Basically, a directive consists of a name, arguments, options and content. (Keep
|
|
this terminology in mind, it is used in the next chapter describing custom
|
|
directives.) Looking at this example, ::
|
|
|
|
.. function:: foo(x)
|
|
foo(y, z)
|
|
:bar: no
|
|
|
|
Return a line of text input from the user.
|
|
|
|
``function`` is the directive name. It is given two arguments here, the
|
|
remainder of the first line and the second line, as well as one option ``bar``
|
|
(as you can see, options are given in the lines immediately following the
|
|
arguments and indicated by the colons).
|
|
|
|
The directive content follows after a blank line and is indented relative to the
|
|
directive start.
|
|
|
|
|
|
Footnotes
|
|
---------
|
|
|
|
For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote
|
|
body at the bottom of the document after a "Footnotes" rubric heading, like so::
|
|
|
|
Lorem ipsum [#]_ dolor sit amet ... [#]_
|
|
|
|
.. rubric:: Footnotes
|
|
|
|
.. [#] Text of the first footnote.
|
|
.. [#] Text of the second footnote.
|
|
|
|
You can also explicitly number the footnotes for better context.
|
|
|
|
|
|
Comments
|
|
--------
|
|
|
|
Every explicit markup block which isn't a valid markup construct (like the
|
|
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.
|
|
|
|
|
|
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.
|