From 0feb7dacf2c3faa2e21c76f662dade00bcfa1811 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 28 Feb 2010 17:24:55 +0100 Subject: [PATCH] Add a bit more content to the reST primer, and add links to the reST reference docs for all constructs. --- doc/conf.py | 6 +- doc/markup/index.rst | 2 + doc/rest.rst | 146 +++++++++++++++++++++++++++++++------------ 3 files changed, 112 insertions(+), 42 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index c487f4866..7e2208484 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,7 +6,7 @@ import re import sphinx extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', - 'sphinx.ext.autosummary'] + 'sphinx.ext.autosummary', 'sphinx.ext.extlinks'] master_doc = 'contents' templates_path = ['_templates'] @@ -49,6 +49,10 @@ latex_elements = { autodoc_member_order = 'groupwise' todo_include_todos = True +extlinks = {'rstref': ('http://docutils.sourceforge.net/docs/ref/rst/' + 'restructuredtext.html#%s', ''), + 'rstdir': ('http://docutils.sourceforge.net/docs/ref/rst/' + 'directives.html#%s', '')} man_pages = [ ('contents', 'sphinx-all', 'Sphinx documentation generator system manual', diff --git a/doc/markup/index.rst b/doc/markup/index.rst index 1127fa739..a39a71a8c 100644 --- a/doc/markup/index.rst +++ b/doc/markup/index.rst @@ -1,3 +1,5 @@ +.. _sphinxmarkup: + Sphinx Markup Constructs ======================== diff --git a/doc/rest.rst b/doc/rest.rst index 87c9f80c5..76fc78d68 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -10,17 +10,19 @@ language, this will not take too long. .. seealso:: - The authoritative `reStructuredText User - Documentation `_. + The authoritative `reStructuredText User Documentation + `_. The "ref" links in this + document link to the description of the individual constructs in the reST + reference. 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. +The paragraph (:rstref:`ref `) 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. .. _inlinemarkup: @@ -52,12 +54,12 @@ provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is ``:rolename:`content```. -Lists and Quotes ----------------- +Lists and Quote-like blocks +--------------------------- -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:: +List markup (:rstref:`ref `) 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 @@ -81,7 +83,7 @@ parent list items by blank lines:: * and here the parent list continues -Definition lists are created as follows:: +Definition lists (:rstref:`ref `) are created as follows:: term (up to a line of text) Definition of the term, which must be indented @@ -91,17 +93,31 @@ Definition lists are created as follows:: next term Description. +Note that the term cannot have more than one line of text. -Paragraphs are quoted by just indenting them more than the surrounding -paragraphs. +Quoted paragraphs (:rstref:`ref `) are created by just indenting +them more than the surrounding paragraphs. + +Line blocks (:rstref:`ref `) are a way of preserving line breaks:: + + | These lines are + | broken exactly like in + | the source file. + +There are also several more special blocks available: + +* field lists (:rstref:`ref `) +* option lists (:rstref:`ref `) +* quoted literal blocks (:rstref:`ref `) +* doctest blocks (:rstref:`ref `) Source Code ----------- -Literal code blocks are introduced by ending a paragraph with the special marker -``::``. The literal block must be indented (and, like all paragraphs, separated -from the surrounding ones by blank lines):: +Literal code blocks (:rstref:`ref `) are introduced by ending a +paragraph with the special marker ``::``. The literal block must be indented +(and, like all paragraphs, separated from the surrounding ones by blank lines):: This is a normal text paragraph. The next paragraph is a code sample:: @@ -124,28 +140,67 @@ That way, the second sentence in the above example's first paragraph would be rendered as "The next paragraph is a code sample:". +Tables +------ + +Two forms of tables are supported. For *grid tables* (:rstref:`ref +`), you have to "paint" the cell grid yourself. They look like +this:: + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | ... | ... | | + +------------------------+------------+---------------------+ + +*Simple tables* (:rstref:`ref `) are easier to write, but +limited: they must contain more than one row, and the first column cannot +contain multiple lines. They look like this:: + + ===== ===== ======= + A B A and B + ===== ===== ======= + False False False + True False False + False True False + True True True + ===== ===== ======= + + Hyperlinks ---------- External links ^^^^^^^^^^^^^^ -Use ```Link text `_`` for inline web links. If the link text -should be the web address, you don't need special markup at all, the parser +Use ```Link text `_`` 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. +You can also separate the link and the target definition (:rstref:`ref +`), like this:: + + This is a paragraph that contains `a link`_. + + .. _a link: http://example.com/ + + Internal links ^^^^^^^^^^^^^^ -Internal linking is done via a special reST role, see the section on specific -markup, :ref:`ref-role`. +Internal linking is done via a special reST role provided by Sphinx, see the +section on specific markup, :ref:`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:: +Section headers (:rstref:`ref `) 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 @@ -170,9 +225,9 @@ target formats (HTML, LaTeX) have a limited supported nesting depth. 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. +"Explicit markup" (:rstref:`ref `) 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 @@ -186,8 +241,17 @@ 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. +A directive (:rstref:`ref `) 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. + +Docutils supports the following directives: + +.. hlist:: + + * XXX + +Directives added by Sphinx are described in :ref:`sphinxmarkup`. 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 @@ -211,7 +275,7 @@ directive start. Images ------ -reST supports an image directive, used like so:: +reST supports an image directive (:rstdir:`ref `), used like so:: .. image:: gnu.png (options) @@ -251,9 +315,9 @@ the former, while the HTML builder would prefer the latter. Footnotes --------- -For footnotes, use ``[#name]_`` to mark the footnote location, and add the -footnote body at the bottom of the document after a "Footnotes" rubric heading, -like so:: +For footnotes (:rstref:`ref `), use ``[#name]_`` 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 [#f1]_ dolor sit amet ... [#f2]_ @@ -269,9 +333,9 @@ footnotes without names (``[#]_``). Citations --------- -Standard reST citations are supported, with the additional feature that they are -"global", i.e. all citations can be referenced from all files. Use them like -so:: +Standard reST citations (:rstref:`ref `) are supported, with the +additional feature that they are "global", i.e. all citations can be referenced +from all files. Use them like so:: Lorem ipsum [Ref]_ dolor sit amet. @@ -284,14 +348,13 @@ numeric or begins with ``#``. Substitutions ------------- -reST supports "substitutions", which are pieces of text and/or markup referred -to in the text by ``|name|``. They are defined like footnotes with explicit -markup blocks, like this:: +reST supports "substitutions" (:rstref:`ref `), which +are pieces of text and/or markup referred to in the text by ``|name|``. They +are defined like footnotes with explicit markup blocks, like this:: .. |name| replace:: replacement *text* -See the `reST reference for substitutions -`_ +See the :rstref:`reST reference for substitutions ` for details. If you want to use some substitutions for all documents, put them into a @@ -307,7 +370,8 @@ Comments -------- Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regarded as a comment. For example:: +footnotes above) is regarded as a comment (:rstref:`ref `). For +example:: .. This is a comment.