diff options
Diffstat (limited to 'Doc/documenting/rest.rst')
| -rw-r--r-- | Doc/documenting/rest.rst | 243 |
1 files changed, 0 insertions, 243 deletions
diff --git a/Doc/documenting/rest.rst b/Doc/documenting/rest.rst deleted file mode 100644 index 9b6b89b..0000000 --- a/Doc/documenting/rest.rst +++ /dev/null @@ -1,243 +0,0 @@ -.. 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. |