Skip to content

Instantly share code, notes, and snippets.

@ionelmc

ionelmc/cheatsheet.rst

Last active May 12, 2025 19:14
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ionelmc/e876b73e2001acd2140f to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ionelmc/e876b73e2001acd2140f to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. ionelmc revised this gist Feb 3, 2015. 1 changed file with 552 additions and 0 deletions.
    552 changes: 552 additions & 0 deletions demonstration.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,552 @@
    .. This is a comment. Note how any initial comments are moved by
    transforms to after the document title, subtitle, and docinfo.
    ================================
    reStructuredText Demonstration
    ================================

    .. Above is the document title, and below is the subtitle.
    They are transformed from section titles after parsing.
    --------------------------------
    Examples of Syntax Constructs
    --------------------------------

    .. bibliographic fields (which also require a transform):
    :Author: David Goodger
    :Address: 123 Example Street
    Example, EX Canada
    A1B 2C3
    :Contact: [email protected]
    :Authors: Me; Myself; I
    :organization: humankind
    :date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $
    :status: This is a "work in progress"
    :revision: $Revision: 7302 $
    :version: 1
    :copyright: This document has been placed in the public domain. You
    may do with it as you wish. You may copy, modify,
    redistribute, reattribute, sell, buy, rent, lease,
    destroy, or improve it, quote it at length, excerpt,
    incorporate, collate, fold, staple, or mutilate it, or do
    anything else to it that your or anyone else's heart
    desires.
    :field name: This is a generic bibliographic field.
    :field name 2:
    Generic bibliographic fields may contain multiple body elements.

    Like this.

    :Dedication:

    For Docutils users & co-developers.

    :abstract:

    This document is a demonstration of the reStructuredText markup
    language, containing examples of all basic reStructuredText
    constructs and many advanced constructs.

    .. meta::
    :keywords: reStructuredText, demonstration, demo, parser
    :description lang=en: A demonstration of the reStructuredText
    markup language, containing examples of all basic
    constructs and many advanced constructs.

    .. contents:: Table of Contents
    .. section-numbering::


    Structural Elements
    ===================

    Section Title
    -------------

    That's it, the text just above this line.

    Transitions
    -----------

    Here's a transition:

    ---------

    It divides the section.

    Body Elements
    =============

    Paragraphs
    ----------

    A paragraph.

    Inline Markup
    `````````````

    Paragraphs contain text and may contain inline markup: *emphasis*,
    **strong emphasis**, ``inline literals``, standalone hyperlinks
    (http://www.python.org), external hyperlinks (Python_), internal
    cross-references (example_), external hyperlinks with embedded URIs
    (`Python web site <http://www.python.org>`__), footnote references
    (manually numbered [1]_, anonymous auto-numbered [#]_, labeled
    auto-numbered [#label]_, or symbolic [*]_), citation references
    ([CIT2002]_), substitution references (|example|), and _`inline
    hyperlink targets` (see Targets_ below for a reference back to here).
    Character-level inline markup is also possible (although exceedingly
    ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by
    |problematic| text (generated by processing errors; this one is
    intentional).

    The default role for interpreted text is `Title Reference`. Here are
    some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
    RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
    and explicit roles for :emphasis:`standard` :strong:`inline`
    :literal:`markup`.

    .. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
    Let's test wrapping and whitespace significance in inline literals:
    ``This is an example of --inline-literal --text, --including some--
    strangely--hyphenated-words. Adjust-the-width-of-your-browser-window
    to see how the text is wrapped. -- ---- -------- Now note the
    spacing between the words of this sentence (words
    should be grouped in pairs).``

    If the ``--pep-references`` option was supplied, there should be a
    live link to PEP 258 here.

    Bullet Lists
    ------------

    - A bullet list

    + Nested bullet list.
    + Nested item 2.

    - Item 2.

    Paragraph 2 of item 2.

    * Nested bullet list.
    * Nested item 2.

    - Third level.
    - Item 2.

    * Nested item 3.

    Enumerated Lists
    ----------------

    1. Arabic numerals.

    a) lower alpha)

    (i) (lower roman)

    A. upper alpha.

    I) upper roman)

    2. Lists that don't start at 1:

    3. Three

    4. Four

    C. C

    D. D

    iii. iii

    iv. iv

    #. List items may also be auto-enumerated.

    Definition Lists
    ----------------

    Term
    Definition
    Term : classifier
    Definition paragraph 1.

    Definition paragraph 2.
    Term
    Definition

    Field Lists
    -----------

    :what: Field lists map field names to field bodies, like database
    records. They are often part of an extension syntax. They are
    an unambiguous variant of RFC 2822 fields.

    :how arg1 arg2:

    The field marker is a colon, the field name, and a colon.

    The field body may contain one or more body elements, indented
    relative to the field marker.

    Option Lists
    ------------

    For listing command-line options:

    -a command-line option "a"
    -b file options can have arguments
    and long descriptions
    --long options can be long also
    --input=file long options can also have
    arguments

    --very-long-option
    The description can also start on the next line.

    The description may contain multiple body elements,
    regardless of where it starts.

    -x, -y, -z Multiple options are an "option group".
    -v, --verbose Commonly-seen: short & long options.
    -1 file, --one=file, --two file
    Multiple options with arguments.
    /V DOS/VMS-style options too

    There must be at least two spaces between the option and the
    description.

    Literal Blocks
    --------------

    Literal blocks are indicated with a double-colon ("::") at the end of
    the preceding paragraph (over there ``-->``). They can be indented::

    if literal_block:
    text = 'is left as-is'
    spaces_and_linebreaks = 'are preserved'
    markup_processing = None

    Or they can be quoted without indentation::

    >> Great idea!
    >
    > Why didn't I think of that?

    Line Blocks
    -----------

    | This is a line block. It ends with a blank line.
    | Each new line begins with a vertical bar ("|").
    | Line breaks and initial indents are preserved.
    | Continuation lines are wrapped portions of long lines;
    they begin with a space in place of the vertical bar.
    | The left edge of a continuation line need not be aligned with
    the left edge of the text above it.
    | This is a second line block.
    |
    | Blank lines are permitted internally, but they must begin with a "|".
    Take it away, Eric the Orchestra Leader!

    | A one, two, a one two three four
    |
    | Half a bee, philosophically,
    | must, *ipso facto*, half not be.
    | But half the bee has got to be,
    | *vis a vis* its entity. D'you see?
    |
    | But can a bee be said to be
    | or not to be an entire bee,
    | when half the bee is not a bee,
    | due to some ancient injury?
    |
    | Singing...
    Block Quotes
    ------------

    Block quotes consist of indented body elements:

    My theory by A. Elk. Brackets Miss, brackets. This theory goes
    as follows and begins now. All brontosauruses are thin at one
    end, much much thicker in the middle and then thin again at the
    far end. That is my theory, it is mine, and belongs to me and I
    own it, and what it is too.

    -- Anne Elk (Miss)

    Doctest Blocks
    --------------

    >>> print 'Python-specific usage examples; begun with ">>>"'
    Python-specific usage examples; begun with ">>>"
    >>> print '(cut and pasted from interactive Python sessions)'
    (cut and pasted from interactive Python sessions)

    Tables
    ------

    Here's a grid table followed by a simple table:

    +------------------------+------------+----------+----------+
    | 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 | Cells may span columns. |
    +------------------------+------------+---------------------+
    | body row 3 | Cells may | - Table cells |
    +------------------------+ span rows. | - contain |
    | body row 4 | | - body elements. |
    +------------------------+------------+----------+----------+
    | body row 5 | Cells may also be | |
    | | empty: ``-->`` | |
    +------------------------+-----------------------+----------+

    ===== ===== ======
    Inputs Output
    ------------ ------
    A B A or B
    ===== ===== ======
    False False False
    True False True
    False True True
    True True True
    ===== ===== ======

    Footnotes
    ---------

    .. [1] A footnote contains body elements, consistently indented by at
    least 3 spaces.
    This is the footnote's second paragraph.
    .. [#label] Footnotes may be numbered, either manually (as in [1]_) or
    automatically using a "#"-prefixed label. This footnote has a
    label so it can be referred to from multiple places, both as a
    footnote reference ([#label]_) and as a hyperlink reference
    (label_).
    .. [#] This footnote is numbered automatically and anonymously using a
    label of "#" only.
    .. [*] Footnotes may also use symbols, specified with a "*" label.
    Here's a reference to the next footnote: [*]_.
    .. [*] This footnote shows the next symbol in the sequence.
    .. [4] Here's an unreferenced footnote, with a reference to a
    nonexistent footnote: [5]_.
    Citations
    ---------

    .. [CIT2002] Citations are text-labeled footnotes. They may be
    rendered separately and differently from footnotes.
    Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
    citation.

    Targets
    -------

    .. _example:

    This paragraph is pointed to by the explicit "example" target. A
    reference can be found under `Inline Markup`_, above. `Inline
    hyperlink targets`_ are also possible.

    Section headers are implicit targets, referred to by name. See
    Targets_, which is a subsection of `Body Elements`_.

    Explicit external targets are interpolated into references such as
    "Python_".

    .. _Python: http://www.python.org/

    Targets may be indirect and anonymous. Thus `this phrase`__ may also
    refer to the Targets_ section.

    __ Targets_

    Here's a `hyperlink reference without a target`_, which generates an
    error.

    Duplicate Target Names
    ``````````````````````

    Duplicate names in section headers or other implicit targets will
    generate "info" (level-1) system messages. Duplicate names in
    explicit targets will generate "warning" (level-2) system messages.

    Duplicate Target Names
    ``````````````````````

    Since there are two "Duplicate Target Names" section headers, we
    cannot uniquely refer to either of them by name. If we try to (like
    this: `Duplicate Target Names`_), an error is generated.

    Directives
    ----------

    .. contents:: :local:

    These are just a sample of the many reStructuredText Directives. For
    others, please see
    http://docutils.sourceforge.net/docs/ref/rst/directives.html.

    Document Parts
    ``````````````

    An example of the "contents" directive can be seen above this section
    (a local, untitled table of contents_) and at the beginning of the
    document (a document-wide `table of contents`_).

    Images
    ``````

    An image directive (also clickable -- a hyperlink reference):

    .. image:: images/title.png
    :target: directives_

    A figure directive:

    .. figure:: images/title.png
    :alt: reStructuredText, the markup syntax

    A figure is an image with a caption and/or a legend:

    +------------+-----------------------------------------------+
    | re | Revised, revisited, based on 're' module. |
    +------------+-----------------------------------------------+
    | Structured | Structure-enhanced text, structuredtext. |
    +------------+-----------------------------------------------+
    | Text | Well it is, isn't it? |
    +------------+-----------------------------------------------+

    This paragraph is also part of the legend.

    Admonitions
    ```````````

    .. Attention:: Directives at large.

    .. Caution::

    Don't take any wooden nickels.

    .. DANGER:: Mad scientist at work!

    .. Error:: Does not compute.

    .. Hint:: It's bigger than a bread box.

    .. Important::
    - Wash behind your ears.
    - Clean up your room.
    - Call your mother.
    - Back up your data.

    .. Note:: This is a note.

    .. Tip:: 15% if the service is good.

    .. WARNING:: Strong prose may provoke extreme mental exertion.
    Reader discretion is strongly advised.

    .. admonition:: And, by the way...

    You can make up your own admonition too.

    Topics, Sidebars, and Rubrics
    `````````````````````````````

    .. sidebar:: Sidebar Title
    :subtitle: Optional Subtitle

    This is a sidebar. It is for text outside the flow of the main
    text.

    .. rubric:: This is a rubric inside a sidebar

    Sidebars often appears beside the main text with a border and
    background color.

    .. topic:: Topic Title

    This is a topic.

    .. rubric:: This is a rubric

    Target Footnotes
    ````````````````

    .. target-notes::

    Replacement Text
    ````````````````

    I recommend you try |Python|_.

    .. |Python| replace:: Python, *the* best language around

    Compound Paragraph
    ``````````````````

    .. compound::

    This paragraph contains a literal block::

    Connecting... OK
    Transmitting data... OK
    Disconnecting... OK
    and thus consists of a simple paragraph, a literal block, and
    another simple paragraph. Nonetheless it is semantically *one*
    paragraph.

    This construct is called a *compound paragraph* and can be produced
    with the "compound" directive.

    Substitution Definitions
    ------------------------

    An inline image (|example|) example:

    .. |EXAMPLE| image:: images/biohazard.png

    (Substitution definitions are not visible in the HTML source.)

    Comments
    --------

    Here's one:

    .. Comments begin with two dots and a space. Anything may
    follow, except for the syntax of footnotes, hyperlink
    targets, directives, or substitution definitions.
    Double-dashes -- "--" -- must be escaped somehow in HTML output.
    (View the HTML source to see the comment.)

    Error Handling
    ==============

    Any errors caught during processing will generate system messages.

    |*** Expect 6 errors (including this one). ***|

    There should be six messages in the following, auto-generated
    section, "Docutils System Messages":

    .. section should be added by Docutils automatically
  2. ionelmc revised this gist Feb 3, 2015. 1 changed file with 132 additions and 0 deletions.
    132 changes: 132 additions & 0 deletions cheatsheet.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,132 @@
    =====================================================
    The reStructuredText_ Cheat Sheet: Syntax Reminders
    =====================================================
    :Info: See <http://docutils.sf.net/rst.html> for introductory docs.
    :Author: David Goodger <[email protected]>
    :Date: $Date: 2013-02-20 01:10:53 +0000 (Wed, 20 Feb 2013) $
    :Revision: $Revision: 7612 $
    :Description: This is a "docinfo block", or bibliographic field list

    .. NOTE:: If you are reading this as HTML, please read
    `<cheatsheet.txt>`_ instead to see the input syntax examples!

    Section Structure
    =================
    Section titles are underlined or overlined & underlined.

    Body Elements
    =============
    Grid table:

    +--------------------------------+-----------------------------------+
    | Paragraphs are flush-left, | Literal block, preceded by "::":: |
    | separated by blank lines. | |
    | | Indented |
    | Block quotes are indented. | |
    +--------------------------------+ or:: |
    | >>> print 'Doctest block' | |
    | Doctest block | > Quoted |
    +--------------------------------+-----------------------------------+
    | | Line blocks preserve line breaks & indents. [new in 0.3.6] |
    | | Useful for addresses, verse, and adornment-free lists; long |
    | lines can be wrapped with continuation lines. |
    +--------------------------------------------------------------------+

    Simple tables:

    ================ ============================================================
    List Type Examples (syntax in the `text source <cheatsheet.txt>`_)
    ================ ============================================================
    Bullet list * items begin with "-", "+", or "*"
    Enumerated list 1. items use any variation of "1.", "A)", and "(i)"
    #. also auto-enumerated
    Definition list Term is flush-left : optional classifier
    Definition is indented, no blank line between
    Field list :field name: field body
    Option list -o at least 2 spaces between option & description
    ================ ============================================================

    ================ ============================================================
    Explicit Markup Examples (visible in the `text source`_)
    ================ ============================================================
    Footnote .. [1] Manually numbered or [#] auto-numbered
    (even [#labelled]) or [*] auto-symbol
    Citation .. [CIT2002] A citation.
    Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html
    .. _indirect target: reStructuredText_
    .. _internal target:
    Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
    Directive ("::") .. image:: images/biohazard.png
    Substitution Def .. |substitution| replace:: like an inline directive
    Comment .. is anything else
    Empty Comment (".." on a line by itself, with blank lines before & after,
    used to separate indentation contexts)
    ================ ============================================================

    Inline Markup
    =============
    *emphasis*; **strong emphasis**; `interpreted text`; `interpreted text
    with role`:emphasis:; ``inline literal text``; standalone hyperlink,
    http://docutils.sourceforge.net; named reference, reStructuredText_;
    `anonymous reference`__; footnote reference, [1]_; citation reference,
    [CIT2002]_; |substitution|; _`inline internal target`.

    Directive Quick Reference
    =========================
    See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.

    ================ ============================================================
    Directive Name Description (Docutils version added to, in [brackets])
    ================ ============================================================
    attention Specific admonition; also "caution", "danger",
    "error", "hint", "important", "note", "tip", "warning"
    admonition Generic titled admonition: ``.. admonition:: By The Way``
    image ``.. image:: picture.png``; many options possible
    figure Like "image", but with optional caption and legend
    topic ``.. topic:: Title``; like a mini section
    sidebar ``.. sidebar:: Title``; like a mini parallel document
    parsed-literal A literal block with parsed inline markup
    rubric ``.. rubric:: Informal Heading``
    epigraph Block quote with class="epigraph"
    highlights Block quote with class="highlights"
    pull-quote Block quote with class="pull-quote"
    compound Compound paragraphs [0.3.6]
    container Generic block-level container element [0.3.10]
    table Create a titled table [0.3.1]
    list-table Create a table from a uniform two-level bullet list [0.3.8]
    csv-table Create a table from CSV data [0.3.4]
    contents Generate a table of contents
    sectnum Automatically number sections, subsections, etc.
    header, footer Create document decorations [0.3.8]
    target-notes Create an explicit footnote for each external target
    math Mathematical notation (input in LaTeX format)
    meta HTML-specific metadata
    include Read an external reST file as if it were inline
    raw Non-reST data passed untouched to the Writer
    replace Replacement text for substitution definitions
    unicode Unicode character code conversion for substitution defs
    date Generates today's date; for substitution defs
    class Set a "class" attribute on the next element
    role Create a custom interpreted text role [0.3.2]
    default-role Set the default interpreted text role [0.3.10]
    title Set the metadata document title [0.3.10]
    ================ ============================================================

    Interpreted Text Role Quick Reference
    =====================================
    See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.

    ================ ============================================================
    Role Name Description
    ================ ============================================================
    emphasis Equivalent to *emphasis*
    literal Equivalent to ``literal`` but processes backslash escapes
    math Mathematical notation (input in LaTeX format)
    PEP Reference to a numbered Python Enhancement Proposal
    RFC Reference to a numbered Internet Request For Comments
    raw For non-reST data; cannot be used directly (see docs) [0.3.6]
    strong Equivalent to **strong**
    sub Subscript
    sup Superscript
    title Title reference (book, etc.); standard default role
    ================ ============================================================
  3. ionelmc revised this gist Feb 3, 2015. 1 changed file with 288 additions and 373 deletions.
    661 changes: 288 additions & 373 deletions primer.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -1,489 +1,404 @@
    .. highlightlang:: rest
    A ReStructuredText Primer
    =========================

    .. _rst-primer:
    :Author: Richard Jones
    :Version: $Revision: 5801 $
    :Copyright: This document has been placed in the public domain.

    reStructuredText Primer
    =======================
    .. contents::

    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 text below contains links that look like "(quickref__)". These
    are relative links that point to the `Quick reStructuredText`_ user
    reference. If these links don't work, please refer to the `master
    quick reference`_ document.

    The authoritative `reStructuredText User Documentation
    <http://docutils.sourceforge.net/rst.html>`_. The "ref" links in this
    document link to the description of the individual constructs in the reST
    reference.
    __
    .. _Quick reStructuredText: quickref.html
    .. _master quick reference:
    http://docutils.sourceforge.net/docs/user/rst/quickref.html

    .. Note:: This document is an informal introduction to
    reStructuredText. The `What Next?`_ section below has links to
    further resources, including a formal reference.

    Paragraphs
    ----------

    The paragraph (:duref:`ref <paragraphs>`) 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.
    Structure
    ---------

    From the outset, let me say that "Structured Text" is probably a bit
    of a misnomer. It's more like "Relaxed Text" that uses certain
    consistent patterns. These patterns are interpreted by a HTML
    converter to produce "Very Structured Text" that can be used by a web
    browser.

    .. _inlinemarkup:
    The most basic pattern recognised is a **paragraph** (quickref__).
    That's a chunk of text that is separated by blank lines (one is
    enough). Paragraphs must have the same indentation -- that is, line
    up at their left edge. Paragraphs that start indented will result in
    indented quote paragraphs. For example::

    Inline markup
    -------------
    This is a paragraph. It's quite
    short.

    The standard reST inline markup is quite simple: use
    This paragraph will result in an indented block of
    text, typically used for quoting other text.

    * one asterisk: ``*text*`` for emphasis (italics),
    * two asterisks: ``**text**`` for strong emphasis (boldface), and
    * backquotes: ````text```` for code samples.
    This is another one.

    If asterisks or backquotes appear in running text and could be confused with
    inline markup delimiters, they have to be escaped with a backslash.
    Results in:

    Be aware of some restrictions of this markup:
    This is a paragraph. It's quite
    short.

    * 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``.
    This paragraph will result in an indented block of
    text, typically used for quoting other text.

    These restrictions may be lifted in future versions of the docutils.
    This is another one.

    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```.
    __ quickref.html#paragraphs

    Standard reST provides the following roles:

    * :durole:`emphasis` -- alternate spelling for ``*emphasis*``
    * :durole:`strong` -- alternate spelling for ``**strong**``
    * :durole:`literal` -- alternate spelling for ````literal````
    * :durole:`subscript` -- subscript text
    * :durole:`superscript` -- superscript text
    * :durole:`title-reference` -- for titles of books, periodicals, and other
    materials
    Text styles
    -----------

    See :ref:`inline-markup` for roles added by Sphinx.
    (quickref__)

    __ quickref.html#inline-markup

    Lists and Quote-like blocks
    ---------------------------
    Inside paragraphs and other bodies of text, you may additionally mark
    text for *italics* with "``*italics*``" or **bold** with
    "``**bold**``". This is called "inline markup".

    List markup (:duref:`ref <bullet-lists>`) 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::
    If you want something to appear as a fixed-space literal, use
    "````double back-quotes````". Note that no further fiddling is done
    inside the double back-quotes -- so asterisks "``*``" etc. are left
    alone.

    * This is a bulleted list.
    * It has two items, the second
    item uses two lines.
    If you find that you want to use one of the "special" characters in
    text, it will generally be OK -- reStructuredText is pretty smart.
    For example, this lone asterisk * is handled just fine, as is the
    asterisk in this equation: 5*6=30. If you actually
    want text \*surrounded by asterisks* to **not** be italicised, then
    you need to indicate that the asterisk is not special. You do this by
    placing a backslash just before it, like so "``\*``" (quickref__), or
    by enclosing it in double back-quotes (inline literals), like this::

    1. This is a numbered list.
    2. It has two items too.
    ``*``

    #. This is a numbered list.
    #. It has two items too.
    __ quickref.html#escaping

    .. Tip:: Think of inline markup as a form of (parentheses) and use it
    the same way: immediately before and after the text being marked
    up. Inline markup by itself (surrounded by whitespace) or in the
    middle of a word won't be recognized. See the `markup spec`__ for
    full details.

    Nested lists are possible, but be aware that they must be separated from the
    parent list items by blank lines::
    __ ../../ref/rst/restructuredtext.html#inline-markup

    * this is
    * a list

    * with a nested list
    * and some subitems
    Lists
    -----

    * and here the parent list continues
    Lists of items come in three main flavours: **enumerated**,
    **bulleted** and **definitions**. In all list cases, you may have as
    many paragraphs, sublists, etc. as you want, as long as the left-hand
    side of the paragraph or whatever aligns with the first line of text
    in the list item.

    Definition lists (:duref:`ref <definition-lists>`) are created as follows::
    Lists must always start a new paragraph -- that is, they must appear
    after a blank line.

    term (up to a line of text)
    Definition of the term, which must be indented
    **enumerated** lists (numbers, letters or roman numerals; quickref__)
    __ quickref.html#enumerated-lists

    and can even consist of multiple paragraphs
    Start a line off with a number or letter followed by a period ".",
    right bracket ")" or surrounded by brackets "( )" -- whatever you're
    comfortable with. All of the following forms are recognised::

    next term
    Description.
    1. numbers

    Note that the term cannot have more than one line of text.
    A. upper-case letters
    and it goes over many lines

    Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
    them more than the surrounding paragraphs.
    with two paragraphs and all!

    Line blocks (:duref:`ref <line-blocks>`) are a way of preserving line breaks::
    a. lower-case letters

    | These lines are
    | broken exactly like in
    | the source file.
    3. with a sub-list starting at a different number
    4. make sure the numbers are in the correct sequence though!

    There are also several more special blocks available:
    I. upper-case roman numerals

    * field lists (:duref:`ref <field-lists>`)
    * option lists (:duref:`ref <option-lists>`)
    * quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
    * doctest blocks (:duref:`ref <doctest-blocks>`)
    i. lower-case roman numerals

    (1) numbers again

    Source Code
    -----------
    1) and again

    Literal code blocks (:duref:`ref <literal-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)::
    Results in (note: the different enumerated list styles are not
    always supported by every web browser, so you may not get the full
    effect here):

    This is a normal text paragraph. The next paragraph is a code sample::
    1. numbers

    It is not processed in any way, except
    that the indentation is removed.
    A. upper-case letters
    and it goes over many lines

    It can span multiple lines.
    with two paragraphs and all!

    This is a normal text paragraph again.
    a. lower-case letters

    The handling of the ``::`` marker is smart:
    3. with a sub-list starting at a different number
    4. make sure the numbers are in the correct sequence though!

    * 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.
    I. upper-case roman numerals

    That way, the second sentence in the above example's first paragraph would be
    rendered as "The next paragraph is a code sample:".
    i. lower-case roman numerals

    (1) numbers again

    .. _rst-tables:
    1) and again

    Tables
    ------
    **bulleted** lists (quickref__)
    __ quickref.html#bullet-lists

    Two forms of tables are supported. For *grid tables* (:duref:`ref
    <grid-tables>`), 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* (:duref:`ref <simple-tables>`) 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
    ----------
    Just like enumerated lists, start the line off with a bullet point
    character - either "-", "+" or "*"::

    External links
    ^^^^^^^^^^^^^^
    * a bullet point using "*"

    Use ```Link text <http://example.com/>`_`` 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.
    - a sub-list using "-"

    You can also separate the link and the target definition (:duref:`ref
    <hyperlink-targets>`), like this::
    + yet another sub-list

    This is a paragraph that contains `a link`_.
    - another item

    .. _a link: http://example.com/
    Results in:

    * a bullet point using "*"

    Internal links
    ^^^^^^^^^^^^^^
    - a sub-list using "-"

    Internal linking is done via a special reST role provided by Sphinx, see the
    section on specific markup, :ref:`ref-role`.
    + yet another sub-list

    - another item

    Sections
    --------
    **definition** lists (quickref__)
    __ quickref.html#definition-lists

    Section headers (:duref:`ref <sections>`) are created by underlining (and
    optionally overlining) the section title with a punctuation character, at least
    as long as the text::
    Unlike the other two, the definition lists consist of a term, and
    the definition of that term. The format of a definition list is::

    =================
    This is a heading
    =================
    what
    Definition lists associate a term with a definition.

    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, this convention is used which you may follow:
    *how*
    The term is a one-line phrase, and the definition is one or more
    paragraphs or body elements, indented relative to the term.
    Blank lines are not allowed between term and definition.

    * ``#`` with overline, for parts
    * ``*`` with overline, for chapters
    * ``=``, for sections
    * ``-``, for subsections
    * ``^``, for subsubsections
    * ``"``, for paragraphs
    Results in:

    Of course, you are free to use your own marker characters (see the reST
    documentation), and use a deeper nesting level, but keep in mind that most
    target formats (HTML, LaTeX) have a limited supported nesting depth.
    what
    Definition lists associate a term with a definition.

    *how*
    The term is a one-line phrase, and the definition is one or more
    paragraphs or body elements, indented relative to the term.
    Blank lines are not allowed between term and definition.

    Explicit Markup
    ---------------

    "Explicit markup" (:duref:`ref <explicit-markup-blocks>`) is used in reST for
    most constructs that need special handling, such as footnotes,
    specially-highlighted paragraphs, comments, and generic directives.
    Preformatting (code samples)
    ----------------------------
    (quickref__)

    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.)
    __ quickref.html#literal-blocks

    To just include a chunk of preformatted, never-to-be-fiddled-with
    text, finish the prior paragraph with "``::``". The preformatted
    block is finished when the text falls back to the same indentation
    level as a paragraph prior to the preformatted block. For example::

    .. _directives:
    An example::

    Directives
    ----------

    A directive (:duref:`ref <directives>`) 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:

    * Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
    :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
    :dudir:`tip`, :dudir:`warning` and the generic
    :dudir:`admonition <admonitions>`. (Most themes style only "note" and
    "warning" specially.)
    Whitespace, newlines, blank lines, and all kinds of markup
    (like *this* or \this) is preserved by literal blocks.
    Lookie here, I've dropped an indentation level
    (but not far enough)

    * Images:
    no more example

    - :dudir:`image` (see also Images_ below)
    - :dudir:`figure` (an image with caption and optional legend)
    Results in:

    * Additional body elements:
    An example::

    - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file
    only, table of contents)
    - :dudir:`container` (a container with a custom class, useful to generate an
    outer ``<div>`` in HTML)
    - :dudir:`rubric` (a heading without relation to the document sectioning)
    - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements)
    - :dudir:`parsed-literal` (literal block that supports inline markup)
    - :dudir:`epigraph` (a block quote with optional attribution line)
    - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own
    class attribute)
    - :dudir:`compound <compound-paragraph>` (a compound paragraph)
    Whitespace, newlines, blank lines, and all kinds of markup
    (like *this* or \this) is preserved by literal blocks.
    Lookie here, I've dropped an indentation level
    (but not far enough)

    * Special tables:
    no more example

    - :dudir:`table` (a table with title)
    - :dudir:`csv-table` (a table generated from comma-separated values)
    - :dudir:`list-table` (a table generated from a list of lists)
    Note that if a paragraph consists only of "``::``", then it's removed
    from the output::

    * Special directives:
    ::

    - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup)
    - :dudir:`include` (include reStructuredText from another file)
    -- in Sphinx, when given an absolute include file path, this directive takes
    it as relative to the source directory
    - :dudir:`class` (assign a class attribute to the next element) [1]_
    This is preformatted text, and the
    last "::" paragraph is removed

    * HTML specifics:
    Results in:

    - :dudir:`meta` (generation of HTML ``<meta>`` tags)
    - :dudir:`title <metadata-document-title>` (override document title)
    ::

    * Influencing markup:
    This is preformatted text, and the
    last "::" paragraph is removed

    - :dudir:`default-role` (set a new default role)
    - :dudir:`role` (create a new role)

    Since these are only per-file, better use Sphinx' facilities for setting the
    :confval:`default_role`.

    Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
    :dudir:`footer`.

    Directives added by Sphinx are described in :ref:`sphinxmarkup`.
    Sections
    --------

    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, ::
    (quickref__)

    __ quickref.html#section-structure

    To break longer text up into sections, you use **section headers**.
    These are a single line of text (one or more words) with adornment: an
    underline alone, or an underline and an overline together, in dashes
    "``-----``", equals "``======``", tildes "``~~~~~~``" or any of the
    non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you
    feel comfortable with. An underline-only adornment is distinct from
    an overline-and-underline adornment using the same character. The
    underline/overline must be at least as long as the title text. Be
    consistent, since all sections marked with the same adornment style
    are deemed to be at the same level::

    Chapter 1 Title
    ===============

    Section 1.1 Title
    -----------------

    Subsection 1.1.1 Title
    ~~~~~~~~~~~~~~~~~~~~~~

    Section 1.2 Title
    -----------------

    Chapter 2 Title
    ===============

    This results in the following structure, illustrated by simplified
    pseudo-XML::

    <section>
    <title>
    Chapter 1 Title
    <section>
    <title>
    Section 1.1 Title
    <section>
    <title>
    Subsection 1.1.1 Title
    <section>
    <title>
    Section 1.2 Title
    <section>
    <title>
    Chapter 2 Title

    (Pseudo-XML uses indentation for nesting and has no end-tags. It's
    not possible to show actual processed output, as in the other
    examples, because sections cannot exist inside block quotes. For a
    concrete example, compare the section structure of this document's
    source text and processed output.)

    Note that section headers are available as link targets, just using
    their name. To link to the Lists_ heading, I write "``Lists_``". If
    the heading has a space in it like `text styles`_, we need to quote
    the heading "```text styles`_``".


    Document Title / Subtitle
    `````````````````````````

    The title of the whole document is distinct from section titles and
    may be formatted somewhat differently (e.g. the HTML writer by default
    shows it as a centered heading).

    To indicate the document title in reStructuredText, use a unique adornment
    style at the beginning of the document. To indicate the document subtitle,
    use another unique adornment style immediately after the document title. For
    example::

    .. function:: foo(x)
    foo(y, z)
    :module: some.module.name
    ================
    Document Title
    ================
    ----------
    Subtitle
    ----------

    Return a line of text input from the user.
    Section Title
    =============

    ``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
    ``module`` (as you can see, options are given in the lines immediately following
    the arguments and indicated by the colons). Options must be indented to the
    same level as the directive content.
    ...

    The directive content follows after a blank line and is indented relative to the
    directive start.
    Note that "Document Title" and "Section Title" above both use equals
    signs, but are distict and unrelated styles. The text of
    overline-and-underlined titles (but not underlined-only) may be inset
    for aesthetics.


    Images
    ------

    reST supports an image directive (:dudir:`ref <image>`), used like so::

    .. image:: gnu.png
    (options)

    When used within Sphinx, the file name given (here ``gnu.png``) must either be
    relative to the source file, or absolute which means that they are relative to
    the top source directory. For example, the file ``sketch/spam.rst`` could refer
    to the image ``images/spam.png`` as ``../images/spam.png`` or
    ``/images/spam.png``.

    Sphinx will automatically copy image files over to a subdirectory of the output
    directory on building (e.g. the ``_static`` directory for HTML output.)

    Interpretation of image size options (``width`` and ``height``) is as follows:
    if the size has no unit or the unit is pixels, the given size will only be
    respected for output channels that support pixels (i.e. not in LaTeX output).
    Other units (like ``pt`` for points) will be used for HTML and LaTeX output.

    Sphinx extends the standard docutils behavior by allowing an asterisk for the
    extension::
    (quickref__)

    .. image:: gnu.*
    __ quickref.html#directives

    Sphinx then searches for all images matching the provided pattern and determines
    their type. Each builder then chooses the best image out of these candidates.
    For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf`
    and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose
    the former, while the HTML builder would prefer the latter.
    Supported image types and choosing priority are defined at :ref:`builders`.
    To include an image in your document, you use the the ``image`` directive__.
    For example::

    Note that image file names should not contain spaces.
    .. image:: images/biohazard.png

    .. versionchanged:: 0.4
    Added the support for file names ending in an asterisk.
    results in:

    .. versionchanged:: 0.6
    Image paths can now be absolute.
    .. image:: images/biohazard.png

    The ``images/biohazard.png`` part indicates the filename of the image
    you wish to appear in the document. There's no restriction placed on
    the image (format, size etc). If the image is to appear in HTML and
    you wish to supply additional information, you may::

    Footnotes
    ---------

    For footnotes (:duref:`ref <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::

    Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

    .. rubric:: Footnotes
    .. image:: images/biohazard.png
    :height: 100
    :width: 200
    :scale: 50
    :alt: alternate text

    .. [#f1] Text of the first footnote.
    .. [#f2] Text of the second footnote.
    See the full `image directive documentation`__ for more info.

    You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
    footnotes without names (``[#]_``).


    Citations
    ---------
    __ ../../ref/rst/directives.html
    __ ../../ref/rst/directives.html#images

    Standard reST citations (:duref:`ref <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::

    Lorem ipsum [Ref]_ dolor sit amet.

    .. [Ref] Book or article reference, URL or whatever.

    Citation usage is similar to footnote usage, but with a label that is not
    numeric or begins with ``#``.


    Substitutions
    -------------

    reST supports "substitutions" (:duref:`ref <substitution-definitions>`), 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*

    or this::

    .. |caution| image:: warning.png
    :alt: Warning!

    See the :duref:`reST reference for substitutions <substitution-definitions>`
    for details.

    If you want to use some substitutions for all documents, put them into
    :confval:`rst_prolog` or put them into a separate file and include it into all
    documents you want to use them in, using the :rst:dir:`include` directive. (Be
    sure to give the include file a file name extension differing from that of other
    source files, to avoid Sphinx finding it as a standalone document.)

    Sphinx defines some default substitutions, see :ref:`default-substitutions`.


    Comments
    --------

    Every explicit markup block which isn't a valid markup construct (like the
    footnotes above) is regarded as a comment (:duref:`ref <comments>`). For
    example::

    .. This is a comment.

    You can indent text after a comment start to form multiline comments::

    ..
    This whole indented block
    is a comment.

    Still in the 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. Sphinx assumes source files to be encoded in UTF-8 by
    default; you can change this with the :confval:`source_encoding` config value.


    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 a
    backslash-escaped space to get around that. See
    :duref:`the reference <substitution-definitions>` for the details.
    What Next?
    ----------

    * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
    possible.
    This primer introduces the most common features of reStructuredText,
    but there are a lot more to explore. The `Quick reStructuredText`_
    user reference is a good place to go next. For complete details, the
    `reStructuredText Markup Specification`_ is the place to go [#]_.

    Users who have questions or need assistance with Docutils or
    reStructuredText should post a message to the Docutils-users_ mailing
    list.

    .. rubric:: Footnotes
    .. [#] If that relative link doesn't work, try the master document:
    http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html.
    .. [1] When the default domain contains a :rst:dir:`class` directive, this directive
    will be shadowed. Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.
    .. _reStructuredText Markup Specification:
    ../../ref/rst/restructuredtext.html
    .. _Docutils-users: ../mailing-lists.html#docutils-users
    .. _Docutils project web site: http://docutils.sourceforge.net/
  4. ionelmc created this gist Feb 3, 2015.
    489 changes: 489 additions & 0 deletions primer.rst
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,489 @@
    .. highlightlang:: rest

    .. _rst-primer:

    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>`_. The "ref" links in this
    document link to the description of the individual constructs in the reST
    reference.


    Paragraphs
    ----------

    The paragraph (:duref:`ref <paragraphs>`) 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:

    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```.

    Standard reST provides the following roles:

    * :durole:`emphasis` -- alternate spelling for ``*emphasis*``
    * :durole:`strong` -- alternate spelling for ``**strong**``
    * :durole:`literal` -- alternate spelling for ````literal````
    * :durole:`subscript` -- subscript text
    * :durole:`superscript` -- superscript text
    * :durole:`title-reference` -- for titles of books, periodicals, and other
    materials

    See :ref:`inline-markup` for roles added by Sphinx.


    Lists and Quote-like blocks
    ---------------------------

    List markup (:duref:`ref <bullet-lists>`) 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 (:duref:`ref <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.

    Note that the term cannot have more than one line of text.

    Quoted paragraphs (:duref:`ref <block-quotes>`) are created by just indenting
    them more than the surrounding paragraphs.

    Line blocks (:duref:`ref <line-blocks>`) 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 (:duref:`ref <field-lists>`)
    * option lists (:duref:`ref <option-lists>`)
    * quoted literal blocks (:duref:`ref <quoted-literal-blocks>`)
    * doctest blocks (:duref:`ref <doctest-blocks>`)


    Source Code
    -----------

    Literal code blocks (:duref:`ref <literal-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)::

    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:".


    .. _rst-tables:

    Tables
    ------

    Two forms of tables are supported. For *grid tables* (:duref:`ref
    <grid-tables>`), 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* (:duref:`ref <simple-tables>`) 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 <http://example.com/>`_`` 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 (:duref:`ref
    <hyperlink-targets>`), 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 provided by Sphinx, see the
    section on specific markup, :ref:`ref-role`.


    Sections
    --------

    Section headers (:duref:`ref <sections>`) 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, this convention is used which you may follow:

    * ``#`` with overline, for parts
    * ``*`` with overline, for chapters
    * ``=``, for sections
    * ``-``, for subsections
    * ``^``, for subsubsections
    * ``"``, for paragraphs

    Of course, you are free to use your own marker characters (see the reST
    documentation), and use a deeper nesting level, but keep in mind that most
    target formats (HTML, LaTeX) have a limited supported nesting depth.


    Explicit Markup
    ---------------

    "Explicit markup" (:duref:`ref <explicit-markup-blocks>`) 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:

    Directives
    ----------

    A directive (:duref:`ref <directives>`) 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:

    * Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
    :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
    :dudir:`tip`, :dudir:`warning` and the generic
    :dudir:`admonition <admonitions>`. (Most themes style only "note" and
    "warning" specially.)

    * Images:

    - :dudir:`image` (see also Images_ below)
    - :dudir:`figure` (an image with caption and optional legend)

    * Additional body elements:

    - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file
    only, table of contents)
    - :dudir:`container` (a container with a custom class, useful to generate an
    outer ``<div>`` in HTML)
    - :dudir:`rubric` (a heading without relation to the document sectioning)
    - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements)
    - :dudir:`parsed-literal` (literal block that supports inline markup)
    - :dudir:`epigraph` (a block quote with optional attribution line)
    - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own
    class attribute)
    - :dudir:`compound <compound-paragraph>` (a compound paragraph)

    * Special tables:

    - :dudir:`table` (a table with title)
    - :dudir:`csv-table` (a table generated from comma-separated values)
    - :dudir:`list-table` (a table generated from a list of lists)

    * Special directives:

    - :dudir:`raw <raw-data-pass-through>` (include raw target-format markup)
    - :dudir:`include` (include reStructuredText from another file)
    -- in Sphinx, when given an absolute include file path, this directive takes
    it as relative to the source directory
    - :dudir:`class` (assign a class attribute to the next element) [1]_

    * HTML specifics:

    - :dudir:`meta` (generation of HTML ``<meta>`` tags)
    - :dudir:`title <metadata-document-title>` (override document title)

    * Influencing markup:

    - :dudir:`default-role` (set a new default role)
    - :dudir:`role` (create a new role)

    Since these are only per-file, better use Sphinx' facilities for setting the
    :confval:`default_role`.

    Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
    :dudir:`footer`.

    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
    directives.) Looking at this example, ::

    .. function:: foo(x)
    foo(y, z)
    :module: some.module.name

    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
    ``module`` (as you can see, options are given in the lines immediately following
    the arguments and indicated by the colons). Options must be indented to the
    same level as the directive content.

    The directive content follows after a blank line and is indented relative to the
    directive start.


    Images
    ------

    reST supports an image directive (:dudir:`ref <image>`), used like so::

    .. image:: gnu.png
    (options)

    When used within Sphinx, the file name given (here ``gnu.png``) must either be
    relative to the source file, or absolute which means that they are relative to
    the top source directory. For example, the file ``sketch/spam.rst`` could refer
    to the image ``images/spam.png`` as ``../images/spam.png`` or
    ``/images/spam.png``.

    Sphinx will automatically copy image files over to a subdirectory of the output
    directory on building (e.g. the ``_static`` directory for HTML output.)

    Interpretation of image size options (``width`` and ``height``) is as follows:
    if the size has no unit or the unit is pixels, the given size will only be
    respected for output channels that support pixels (i.e. not in LaTeX output).
    Other units (like ``pt`` for points) will be used for HTML and LaTeX output.

    Sphinx extends the standard docutils behavior by allowing an asterisk for the
    extension::

    .. image:: gnu.*

    Sphinx then searches for all images matching the provided pattern and determines
    their type. Each builder then chooses the best image out of these candidates.
    For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf`
    and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose
    the former, while the HTML builder would prefer the latter.
    Supported image types and choosing priority are defined at :ref:`builders`.

    Note that image file names should not contain spaces.

    .. versionchanged:: 0.4
    Added the support for file names ending in an asterisk.

    .. versionchanged:: 0.6
    Image paths can now be absolute.


    Footnotes
    ---------

    For footnotes (:duref:`ref <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::

    Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

    .. rubric:: Footnotes

    .. [#f1] Text of the first footnote.
    .. [#f2] Text of the second footnote.

    You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
    footnotes without names (``[#]_``).


    Citations
    ---------

    Standard reST citations (:duref:`ref <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::

    Lorem ipsum [Ref]_ dolor sit amet.

    .. [Ref] Book or article reference, URL or whatever.

    Citation usage is similar to footnote usage, but with a label that is not
    numeric or begins with ``#``.


    Substitutions
    -------------

    reST supports "substitutions" (:duref:`ref <substitution-definitions>`), 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*

    or this::

    .. |caution| image:: warning.png
    :alt: Warning!

    See the :duref:`reST reference for substitutions <substitution-definitions>`
    for details.

    If you want to use some substitutions for all documents, put them into
    :confval:`rst_prolog` or put them into a separate file and include it into all
    documents you want to use them in, using the :rst:dir:`include` directive. (Be
    sure to give the include file a file name extension differing from that of other
    source files, to avoid Sphinx finding it as a standalone document.)

    Sphinx defines some default substitutions, see :ref:`default-substitutions`.


    Comments
    --------

    Every explicit markup block which isn't a valid markup construct (like the
    footnotes above) is regarded as a comment (:duref:`ref <comments>`). For
    example::

    .. This is a comment.

    You can indent text after a comment start to form multiline comments::

    ..
    This whole indented block
    is a comment.

    Still in the 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. Sphinx assumes source files to be encoded in UTF-8 by
    default; you can change this with the :confval:`source_encoding` config value.


    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 a
    backslash-escaped space to get around that. See
    :duref:`the reference <substitution-definitions>` for the details.

    * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
    possible.


    .. rubric:: Footnotes

    .. [1] When the default domain contains a :rst:dir:`class` directive, this directive
    will be shadowed. Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.