******************************* :mod:`ReST` -- reStructuredText ******************************* .. module:: ReST :synopsis: reStructuredText Memo .. moduleauthor:: Marc Zonzon .. highlight:: rest A simple markup language for plain text files. .. contents:: :local: :depth: 1 Structural elements =================== .. contents:: :local: .. index:: single: emacs; mode Emacs ReST mode --------------- ======================= ========================================== ``C-c C-=`` Adjust/rotate or promote/demote the decorations ``C-- C-c C-=`` reverse Adjust ``C-c C-a C-d`` Display the title decoration hierarchy. ``C-- C-c C-r `` shift region left ``C-c C-r `` shift region right ``C-c C-t C-t`` display a table of content to navigate buffer ======================= ========================================== Sectioning ---------- .. index:: !title single: title; hierarchy Titles are under- (and over-)lined (decorated) by ``=*-^"~`:.'#`` as below. The exact order of the decoration is not important, the one below is the `Python convention `_. +------------------------------+------------------------------+ | :: | :: | | | | | #### | | | Part | Subsection | | #### | ---------- | | | | | ********* | | | Chapter | Subsubsection | | ********* | ^^^^^^^^^^^^^ | | | | | Section | Paragraph | | ======= | """"""""" | | | | +------------------------------+------------------------------+ Normal paragraphs are separated by a blank line. A ``=`` with overlines is very often preferred to a ``*`` with overlines for chapters. The previously quoted `Python development guide `_ while advising to use stars uses internally equal character. `Docutils documentation `_ uses overlined ``=`` for parts, overlined ``-`` for chapters, ``=`` for sections, ``-`` for subsections, back quotes (`) for subsubsections. Transition ---------- Any repetition of 4 or more punctuation characters with preceding and trailing blank line is a transition, and looks like this: ---- .. index:: emphasize strong code inline markup inline markup; strong inline markup; emphasize inline markup; code .. _rest_inline_markup: Inline markup ============= ========================== ====================== ``*emphasize*`` *emphasize* ``**emphasize strongly**`` **emphasize strongly** ````code```` ``code`` ```don't know``` `don't know` ``Asterisk \*`` Asterisk \* ``back-quote \``` back-quote \` ``**mark**\ up.`` **mark**\ up. ========================== ====================== See :restref:`inline markup reference `. .. _rest_roles: ReStructuredText Text Roles. ---------------------------- The :restref:`ReStructuredText Interpreted Text Roles ` are valid both for reST and Sphinx processing. They are: ``:emphasis:``, ``:strong:``, ``:literal:``, ``:code:``, ``:math:``, ``:pep-reference:``, ``:rfc-reference:``, ``:subscript:``, ``:superscript:``, ``:title-reference:``, ``:raw:``. The first three are seldom used because we prefer the shortcuts provided by previous :ref:`reST inline markup `. The :restref:`Custom Interpreted Text Roles ` which is a reST directive ``role``, the tailor the renderer to apply some special formatting. We use it :ref:`in Sphinx section ` to use a special css class for some span of text. .. index:: !list Lists ===== .. contents:: :local: .. index:: single: list; bullet single: list; itemize bullet list Bullet list ----------- :: - First item with some lengthy text wrapping hopefully across several lines. * We can have subitems * separated by a blank line * and indented. - Second item - First item with some lengthy text wrapping hopefully across several lines. * We can have subitems * separated by a blank line * and indented. - Second item We can begin each item with ``*``, ``+``, ``-``, ``•``, ``‣``, or ``⁃`` followed by at least one space, you should keep the indentation of the text of the first line in subsequent lines. See :restref:`bullet list reference` .. index:: single: list; horizontal horizontal list Horizontal lists ---------------- :: .. hlist:: :columns: 3 * list of * short items * that should be * displayed * horizontally .. hlist:: :columns: 3 * list of * short items * that should be * displayed * horizontally *hlist is a sphinx extension, not a ReST directive* .. index:: single: list; enumerated enumerated list Enumerated list --------------- :: 2. We start with point number 2 #. Automatically numbered item. a) Point a i) first subitem ii) second subitem b) Point b #) Automatic point c. 2. We start with point number 2 #. Automatically numbered item. a) Point a i) first subitem ii) second subitem b) Point b #) Automatic point c. We can use enumerate with numerals, alphabetic lower case or upper case, roman numerals lower case or upper case. We can write enumeration followed by a period, a right parenthesis, or surrounded by a parentheses; but these punctuation are not kept in the rendering; *rst2html* render ``i.``, ``i)`` or ``(i)`` as "i." and Sphinx render them as "a.". A list must be separated from previous paragraph by a blank line, in the same way sublists must be separated from items of upper list by a blank line. Any break of sequence in the source, produces a new list. See :restref:`enumerated list reference `. .. index:: single: list; definition definition list .. _definition_list: Definition list --------------- :: what Definition of "what". We add a few words to show the line wrapping. how Definition of "how". why : We define "why" we do it. In many paragraphs what Definition of "what". We add a few words to show the line wrapping. how Definition of "how". why : cause We define "why" we do it. In many paragraphs. With ReST but not Sphinx you can use a classifier after the main term like :: why : cause We define "why" we do it. We may have to escape a markup character to clear ambiguity between a definition list and an other construct like: :: \(w) This is a definition list, not an enumeration. See :restref:`definition list reference `. .. index:: pair: list; field .. _field list: Field list ---------- .. list-table:: :widths: 40, 60 * - .. code-block:: ReST :Name: Isaac Newton :Long: Here we insert more text in many lines. :Remark: Starts on the next line. - :Name: Isaac Newton :Long: Here we insert more text in many lines. :Remark: Starts on the next line. See :restref:`field list reference `. .. index:: single: list; options Options list ------------ E.g. for listing command line options. .. list-table:: :widths: 40, 60 * - .. code-block:: ReST -v An option -o file Same with value --delta A long option --delta=len Same with value --option-name-is-long description on the next line. - -v An option -o file Same with value --delta A long option --delta=len Same with value --option-name-is-long description on the next line. It is nice to align option descriptions, but not mandatory, but at least two spaces must separate an option from the description. .. index:: !block single: block; literal literal block Blocks ====== .. contents:: :local: .. _literal_block: Literal Block ------------- :restref:`rest literal blocks ` A block which is not interpreted at all is preceded by a paragraph consisting of ``::`` and a blank line. The block must be indented. The double ``::`` is removed from the output. To use a specific formatting, you can use the :ref:`code directive ` .. list-table:: :widths: 50, 50 * - .. code-block:: ReST Block one :: **No** interpretation of |special| characters. - Block one :: **No** interpretation of |special| characters. You can also put the ``::`` at the end of the paragraph preceding the block. When text immediately precedes the ``::`` the two colons are displayed as ":", if there is a space before the colons they are removed from the output. .. list-table:: :widths: 50, 50 * - .. code-block:: ReST Block in condensed syntax:: - I'm not a list. - Block in condensed syntax:: - I'm not a list. * - .. code-block:: ReST Another block! :: In the text body, indentation is preserved - Another block! :: In the text body, indentation is preserved .. warning:: *Sphinx* use literal blocks to :ref:`highlight source code `, so ``**No**`` is still written with a bold font by *Sphinx* while being not interpreted by *rst2html*. To disable *Pygment* decorations in *Sphinx* use a :ref:`code block ` in ``text`` language. .. index:: single: block; line single: quotes; line block Line blocks ----------- In a line block (:restref:`ref `) every line is preceded with ``|`` and at least one space. .. list-table:: :widths: 50, 50 * - .. code-block:: ReST | Line block | New line and we are still on the same line | Yet a new line - | Line block | New line and we are still on the same line | Yet a new line .. index:: pair: block; quotes !blockquote .. _blockquote: Block quote ----------- :: created by ... surrounding paragraph. Neither from itself nor from another, Nor from both, Nor without a cause, Does anything whatever, anywhere arise. --Nagarjuna - *Mulamadhyamakakarika* Block quotes (:restref:`ref `) are created by just indenting them more than the surrounding paragraphs. Neither from itself nor from another, Nor from both, Nor without a cause, Does anything whatever, anywhere arise. --Nagarjuna - *Mulamadhyamakakarika* An optional attribution can be set by a line beginning by two or three minus signs flushed left at the level of the quote. .. index:: pair:directive; pull-quote .. _pull-quote: Pull-quote ---------- Pull-quotes (:restref:`ref `) are similar to blockquotes but are :ref:`directives ` .. code-block:: ReST .. pull-quote:: Just as a solid ... .. pull-quote:: Just as a solid rock is not shaken by the storm, even so the wise are not affected by praise or blame. .. index:: single: blockquote; epigraph single: blockquote; highlights directive; epigraph directive; highlights .. _epigraph: Epigraph and highlights ----------------------- An `epigraph` directive (:restref:`ref `) and an `highlights` directive (:restref:`ref `) are aimed to put a quotation in a distinct font. *don't forget the final* **s** *of highlights, or you fall down on the* :ref:`Sphinx code highlighting directive ` .. code-block:: ReST .. highlights:: With these *highlights* ... .. highlights:: With these *highlights* we have completed the ReST blocks. These three directives are similar in html rendering to :ref:`blockquote` but with a `class` of ``pull-quote``, ``highlights`` or ``epigraph`` that your css may use *but default css does not!* .. index:: block; container pair: directive; container .. _container: Container --------- .. code-block:: ReST .. container:: myclass There is also a general ... .. container:: myclass There is also a general :restref:`container directive ` whose unique effect is adding some class name to the block that your css may use. In html this paragraph is enclosed in a .. code-block:: html
...
.. index:: pair: directive; class .. _class_directive: Class ----- .. code-block:: ReST .. class:: myclass The class directive .... .. class:: myclass The class directive (:restref:`ref `) add a class on its content or on the first immediately following non-comment element. The name of the class is normalized by docutil to conform to the regexp: ``[a-z](-?[a-z0-9]+)*``. .. note:: While the docutil tool ``rst2html`` put as expected the previous paragraph in a::

....

Sphinx shadows the class directive, so the previous code will not have the expected result. In Sphinx you have to replace ``class`` by ``rst-class``. .. index:: !table Tables ====== .. contents:: :local: .. index:: pair: table; simple .. _simple_table: Simple tables ------------- .. sidebar:: Code for the examples :: == == aA bB cC dD == == ===== ====== Vokal Umlaut ===== ====== aA äÄ oO öÖ ===== ====== ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False ------------ ------ True False True False True True True True ============ ====== =========== ================ 1. Hallo | blah blah blah blah blah blah blah | blah blah 2. Here We can wrap the text in source 32. There **aha** =========== ================ Simple tables (:restref:`ref `) are preceded and ended with a sequence of "``=``" to indicate the columns, e.g: == == aA bB cC dD == == Headers are indicated by another sequence of "``=``", e.g: ===== ====== Vokal Umlaut ===== ====== aA äÄ oO öÖ ===== ====== Column spans are followed by a sequence of "``-``" (except for the last header or last row of the table where we must have "``=``"), e.g: ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False ------------ ------ True False True False True True True True ============ ====== Simple table cells are treated like a small document on their own up to line breaks, but the first column must contain a single line. e.g: =========== ================ 1. Hallo | blah blah blah blah blah blah blah | blah blah 2. Here We can wrap the text in source 32. There **aha** =========== ================ .. index:: pair: grid; table .. _grid_table: Grid tables ----------- .. sidebar:: Code for example :: +--------+--------+-----------+ | Header | Header with 2 cols | +========+========+===========+ | A | Lists: | **C** | +--------+ - aha +-----------+ | B:: | - yes | | a block | | | | of text | | *hey* | #. hi | | a break | +--------+--------+-----------+ Grid tables (:restref:`ref `) have a more difficult syntax but can express more complex tables. .. only:: latex .. tabularcolumns:: |p{0.15\linewidth}|p{0.15\linewidth}|p{0.15\linewidth}| +--------+--------+-----------+ | Header | Header with 2 cols | +========+========+===========+ | A | Lists: | **C** | +--------+ - aha +-----------+ | B:: | - yes | | a block | | | | of text | | *hey* | #. hi | | a break | +--------+--------+-----------+ .. index:: table; emacs You can edit them under emacs with ``table.el`` (but be careful about conflicts with ``rst-mode``) or use *org tables* with ``orgtbl-mode`` and export to table with ``org-table-convert`` or ``org-table-create-with-table.el`` ( bound to :kbd:`C-c ~` in ``org-mode``, but not in ``orgtbl-mode``) .. index:: triple: directive; table; csv .. _csv_table: csv table. ---------- .. sidebar:: Code .. code-block:: ReST .. csv-table:: Balance Sheet :header: Description,In,Out,Balance :widths: 20, 10, 10, 10 :stub-columns: 1 Travel,,230.00,-230.00 Fees,,400.00,-630.00 Grant,700.00,,70.00 Train Fare,,70.00,**0.00** .. csv-table:: Balance Sheet :header: Description,In,Out,Balance :widths: 20, 10, 10, 10 :stub-columns: 1 Travel,,230.00,-230.00 Fees,,400.00,-630.00 Grant,700.00,,70.00 Train Fare,,70.00,**0.00** The options are explained in the reference: :restref:`rst directive: csv-table ` You can choose a delimiter with ``:delim:`` and source an external file with the option ``:file:/path/of/the/file``. .. index:: triple: directive; table; list .. _list_table: List Table. ----------- A list-table (:restref:`ref `) is a two level list, where the first level is a row and the second one a column list. The number of column must be uniform (*no column span*) but cell may contain structured markup. .. code-block:: ReST .. list-table:: Weather forecast :header-rows: 1 :widths: 7 7 7 7 60 :stub-columns: 1 * - Day - Min Temp - Max Temp - - Summary * - Monday - 11C - 22C - .. image:: _static/sunny.svg :width: 30 - A clear day with lots of sunshine. However, the strong breeze will bring down the temperatures. * - Tuesday - 9C - 10C ... .. list-table:: Weather forecast :header-rows: 1 :widths: 7 7 7 7 60 :stub-columns: 1 * - Day - Min Temp - Max Temp - - Summary * - Monday - 11C - 22C - .. only:: not latex .. image:: _static/sunny.svg :width: 30 .. only:: latex .. image:: _static/sunny.pdf :width: 30 - A clear day with lots of sunshine. However, the strong breeze will bring down the temperatures. * - Tuesday - 9C - 10C - .. only:: not latex .. image:: _static/cloudy.svg :width: 30 .. only:: latex .. image:: _static/cloudy.pdf :width: 30 - Cloudy with rain, across many northern regions. Clear spells across most of Scotland and Northern Ireland, but rain reaching the far northwest. .. index:: pair: table; latex LaTeX table rendering. ---------------------- .. index:: latex; tabulary Rendering with *tabulary*. ^^^^^^^^^^^^^^^^^^^^^^^^^^ Sphinx use the latex package `tabulary `_ to render tables in laTeX. Tabulary is an extension of the *tabular* package which calculate the width of columns; it has four new formats specifications: ``LRCJ`` for Left (Right, Centered, Justified) column with automatic width. Sphinx uses by default ``L``, but you can override it with a directive like:: .. tabularcolumns:: |L|C|C|R| As examples in this document the :ref:`source code directives table ` which has a proper Sphinx automatic rendering in tabulary ``|L|L|``, which adapt the column size with a wider left one. The two first :ref:`simple tables ` the :ref:`csv table ` and the :ref:`list table ` are also rendered in `tabulary` with a proper calculation of table width by latex. .. index:: latex; tabular Rendering with *tabular*. ^^^^^^^^^^^^^^^^^^^^^^^^^ Tables that contain any kind of lists, such as object descriptions, blockquotes, or literal blocks are set by default with the `tabular `_. In sphinx prior version 1.6 the `:column:` option for list table is not used for latex, and all columns are of the same size. You can tailor the rendering by giving `tabularcolumns` directive which uses the `p{width}` column type. Like this for three uneven columns: .. code-block:: ReST .. tabularcolumns:: |p{0.10\linewidth}|p{0.10\linewidth}|p{0.30\linewidth}| .. _cross_reference: Cross reference. ================ .. contents:: :local: .. index:: hyperlink pair: hypertext; link pair: hypertext; target reference ref pair: reference; target pair: reference; label pair: reference; cross pair: reference; indirect Hypertext link. --------------- Hypertext links are constituted of a reference and a target. And there are four types of hyperlink targets: 1. An external hyperlink target is an URI or an email addresses like .. code-block:: ReST _Docutils: http://docutils.sourceforge.net/ _John Lee: john.lee@gmail.com It is possible, but not recommended, to avoid the target reference by using an `anonymous hyperlink`_. 2. An :ref:`explicit hyperlink target ` is an internal document reference which point to some location in the same document. 3. An `indirect hyperlink`_ has an other hyperlink reference as target. 4. An `implicit hyperlink target`_ is generated by the *docutil* ReST processor, for all sections of the document. There exist three ways to write hyperlink references (:restref:`ref`) 1. In `Citation Style`_ 2. Inline with an `Embedded URI`_ which gives in the same construct both the reference and the target. 3. In a `standalone hyperlink`_ the text of the target URI is used as reference. .. index:: pair: internal; reference pair: option; name .. _explicit_target: Explicit hyperlink target ------------------------- .. _internal: An :restref:`explicit hyperlink target ` is an *internal document reference* for any text location. You define it by preceding the text location with: .. code-block:: ReST .. _label: .. _other label: plus a blank line. A ``:name:`` option in any block is also an internal reference target. You can also use :restref:`inline internal targets ` :: which are a _`span of running text` in a paragraph. .. _rest_ref: The ReST way of referencing a label or :restref:`hyperlink targets ` is: .. code-block:: ReST label_ or `other label`_ .. index:: pair: indirect; hyperlink pair: hyperlink; alias The explicit hyperlink targets need to be unique in the document, and if you use them with Sphinx to be unique in the set of project documents. They override any identical implicit target. Oneness of reference is easier to maintain with explicit rather implicit targets. .. _indirect hyperlink: Indirect Hyperlink. ------------------- If for the same hyperlink target you want to use a you want to use many references you can use an *indirect hyperlink* or *indirect reference*. With the following indirect references pocoo_, Sphinx_, `The manual`_ and Documentation_ refer to the same place. Like above don't forget backquotes when there are embedded whitespaces. .. code-block:: ReST .. _pocoo: http://sphinx.pocoo.org .. _Sphinx: pocoo_ .. _The manual: pocoo_ .. _Documentation: `The manual`_ .. _Sphinx Home: http://sphinx.pocoo.org .. _pocoo: http://sphinx.pocoo.org .. _Sphinx: pocoo_ .. _The manual: pocoo_ .. _Documentation: `The manual`_ Note that if you only want to have multiple link text with the same target you can also use: .. code-block:: ReST .. _Sphinx: .. _The manual: .. _pocoo: http://sphinx.pocoo.org Multiple adjacent hyperlink references will all point to the same target. An indirect hyperlink can also be defined inline with an `embedded alias`_. .. index:: pair: hyperlink; anonymous .. _anonymous hyperlink: Anonymous Hyperlink ------------------- :restref:`Anonymous hyperlinks ` are hyperlinks where the target has no label text but begins with double leading underscores, the reference itself ends with two trailing underscores. The targets are found by their sequential order in the document. The reference number *n*, reference the target number *n*. Example: .. code-block:: ReST .. __: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html The `ReST reference manual`__ .. __: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html The `ReST reference manual`__ The anonymous hyperlinks make the source text quite obscure, as the association between reference and targets can only be seen by enumerating both. They break easily. Moving a bloc of text with either a target or reference invalidate all anonymous hyperlinks of the document. So it is wise to avoid them. .. index:: hyperlink; implicit target implicit; hyperlink .. _implicit hyperlink target: .. _implicit hyperlink: Implicit Hyperlink Targets -------------------------- Section titles, footnotes, and citations automatically are :restref:`implicit hyperlink targets `. To give an example in the present document, under the section `Structural elements`_ you find a subsection named `Transition`_. This section does not have any explicit hyperlink target, but when you write in the text ```Transition`_`` it produces `Transition`_. .. _indirect reference to an implicit target: In pure ReST syntax you can reference the `Transition`_ section as `how to draw an horizontal line`_ with the hyperlink: ```how to draw an horizontal line`_`` and the `indirect hyperlink`_: .. code-block:: ReST .. _how to draw an horizontal line: Transition_ .. _how to draw an horizontal line: Transition_ You can also use them with an `embedded alias`_ .. list-table:: * - .. code-block:: ReST | The `Transition section `_ shows | `how to draw an horizontal line`_ in your document. - | The `Transition section `_ shows | `how to draw an horizontal line`_ in your document. Implicit targets are easily broken, rewording a section title, or evenfixing a typo, changing a punctuation, break all the references. And when modifying a title you don't always think it might be a link target somewhere in the document. You don't modify so often the explicit link targets, and when you do it, you know that you have also to fix all references. So you should put away implicit in favor of explicit. .. index:: reference; citation style .. _citation style: Reference in citation style. ---------------------------- .. code-block:: ReST A link to `Sphinx Home`_ in citation style. .. _Sphinx Home: http://sphinx.pocoo.org A link to `Sphinx Home`_ in citation style ( :restref:`ref `). In printed documents the link will be listed similar as a citation, as opposed to HTML documents. .. _reference name: The reference target is composed of words made of alphabetic and numeric characters and characters in the set ``[,:_+-]`` *without double hyphens*, separated by spaces. (:restref:`ref `). The references are equivalents when they differ only by case or number of spaces. The space character class include spaces, horizontal or vertical tabs, newlines, carriage returns, or form feeds. When the reference has no embedded spaces the backquotes are not necessary: .. code-block:: ReST A link to Sphinx_ in citation style. If you want to use a |styledref|_ you have to use a ref:`replacement`. .. |styledref| replace:: *styled* reference .. _styledref: `styled reference`_ .. index:: pair: reference; embedded pair: reference; in-line pair: hyperlink; embedded pair: alias; embedded .. _embedded uri: .. _embedded alias: Embedded URI and Aliases ------------------------ Reference: :restref:`ref ` You can directly embed an URI, a link target or an internal label in a reference enclosed in ``<``, ``>`` in the reference. In the same way than explicit :ref:`indirect hyperlink` when we use a target defined elsewhere we have use a trailing underscore. In the last example we use the label ``explicit_target`` placed before a section at the beginning of this document. .. list-table:: * - .. code-block:: ReST In-line versions is `Sphinx Home `_ - In-line versions is `Sphinx Home `_. * - .. code-block:: ReST .. _devguide: http://docs.python.org/devguide/ `Python development `_ - .. _devguide: http://docs.python.org/devguide/ `Python development `_ * - .. code-block:: ReST `Sphinx main page `_ - `Sphinx main page `_ * - .. code-block:: ReST `Internal target `_ - `Internal target `_ .. index:: pair: hyperlink; standalone .. _standalone hyperlink: Standalone Hyperlink. --------------------- Reference: :restref:`ref ` .. list-table:: * - .. code-block:: ReST | We may use URI like http://sphinx.pocoo.org or | an email address like project@sphinx.org - | We may use URI like http://sphinx.pocoo or | an email address like project@sphinx.org .. index: Sphinx reference; vs ReST ReST reference; vs Sphinx .. _sphinx vs rest references: Difference between ReST and Sphinx location reference ----------------------------------------------------- Sphinx has its own *preferred syntax*, it uses: .. code-block:: ReST :ref:`displayed text