Move the 3k reST doc tree in place.

1 files changed, 251 insertions, 0 deletions

diff --git a/Doc/documenting/rest.rst b/Doc/documenting/rest.rst
new file mode 100644
index 0000000..8a4fc3d
--- /dev/null
+++ b/Doc/documenting/rest.rst
@@ -0,0 +1,251 @@
+.. 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.
+
+Note that Sphinx disables the use of enumerated lists introduced by alphabetic
+or roman numerals, such as ::
+
+   A. First item
+   B. Second item
+   
+
+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, to be able to include blank lines::
+
+   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.
+
+.. XXX more?