docs/user/rst/cheatsheet.txt

   1 =====================================================
   2  The reStructuredText_ Cheat Sheet: Syntax Reminders
   3 =====================================================
   4 :Info: See <http://docutils.sf.net/rst.html> for introductory docs.
   5 :Author: David Goodger <goodger@python.org>
   6 :Date: $Date$
   7 :Revision: $Revision$
   8 :Description: This is a "docinfo block", or bibliographic field list
   9
  10 Section Structure
  11 =================
  12 Section titles are underlined or overlined & underlined.
  13
  14 Body Elements
  15 =============
  16 Grid table:
  17
  18 +--------------------------------+-----------------------------------+
  19 | Paragraphs are flush-left,     | Literal block, preceded by "::":: |
  20 | separated by blank lines.      |                                   |
  21 |                                |     Indented                      |
  22 |     Block quotes are indented. |                                   |
  23 +--------------------------------+ or::                              |
  24 | >>> print 'Doctest block'      |                                   |
  25 | Doctest block                  | > Quoted                          |
  26 +--------------------------------+-----------------------------------+
  27 | | Line blocks preserve line breaks & indents. [new in 0.3.6]       |
  28 | |     Useful for addresses, verse, and adornment-free lists; long  |
  29 |       lines can be wrapped with continuation lines.                |
  30 +--------------------------------------------------------------------+
  31
  32 Simple tables:
  33
  34 ================  ============================================================
  35 List Type         Examples
  36 ================  ============================================================
  37 Bullet list       * items begin with "-", "+", or "*"
  38 Enumerated list   1. items use any variation of "1.", "A)", and "(i)"
  39                   #. also auto-enumerated
  40 Definition list   Term is flush-left : optional classifier
  41                       Definition is indented, no blank line between
  42 Field list        :field name: field body
  43 Option list       -o  at least 2 spaces between option & description
  44 ================  ============================================================
  45
  46 ================  ============================================================
  47 Explicit Markup   Examples (visible in the `text source <cheatsheet.txt>`_)
  48 ================  ============================================================
  49 Footnote          .. [1] Manually numbered or [#] auto-numbered
  50                      (even [#labelled]) or [*] auto-symbol
  51 Citation          .. [CIT2002] A citation.
  52 Hyperlink Target  .. _reStructuredText: http://docutils.sf.net/rst.html
  53                   .. _indirect target: reStructuredText_
  54                   .. _internal target:
  55 Anonymous Target  __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html
  56 Directive ("::")  .. image:: images/biohazard.png
  57 Substitution Def  .. |substitution| replace:: like an inline directive
  58 Comment           .. is anything else
  59 Empty Comment     (".." on a line by itself, with blank lines before & after,
  60                   used to separate indentation contexts)
  61 ================  ============================================================
  62
  63 Inline Markup
  64 =============
  65 *emphasis*; **strong emphasis**; `interpreted text`; `interpreted text
  66 with role`:emphasis:; ``inline literal text``; standalone hyperlink,
  67 http://docutils.sourceforge.net; named reference, reStructuredText_;
  68 `anonymous reference`__; footnote reference, [1]_; citation reference,
  69 [CIT2002]_; |substitution|; _`inline internal target`.
  70 \f
  71 Directive Quick Reference
  72 =========================
  73 See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info.
  74
  75 ================  ============================================================
  76 Directive Name    Description (Docutils version added to, in [brackets])
  77 ================  ============================================================
  78 attention         Specific admonition; also "caution", "danger",
  79                   "error", "hint", "important", "note", "tip", "warning"
  80 admonition        Generic titled admonition: ``.. admonition:: By The Way``
  81 image             ``.. image:: picture.png``; many options possible
  82 figure            Like "image", but with optional caption and legend
  83 topic             ``.. topic:: Title``; like a mini section
  84 sidebar           ``.. sidebar:: Title``; like a mini parallel document
  85 parsed-literal    A literal block with parsed inline markup
  86 rubric            ``.. rubric:: Informal Heading``
  87 epigraph          Block quote with class="epigraph"
  88 highlights        Block quote with class="highlights"
  89 pull-quote        Block quote with class="pull-quote"
  90 compound          Compound paragraphs [0.3.6]
  91 container         Generic block-level container element [0.3.10]
  92 table             Create a titled table [0.3.1]
  93 list-table        Create a table from a uniform two-level bullet list [0.3.8]
  94 csv-table         Create a table from CSV data [0.3.4]
  95 contents          Generate a table of contents
  96 sectnum           Automatically number sections, subsections, etc.
  97 header, footer    Create document decorations [0.3.8]
  98 target-notes      Create an explicit footnote for each external target
  99 math              Mathematical notation (input in LaTeX format)
 100 meta              HTML-specific metadata
 101 include           Read an external reST file as if it were inline
 102 raw               Non-reST data passed untouched to the Writer
 103 replace           Replacement text for substitution definitions
 104 unicode           Unicode character code conversion for substitution defs
 105 date              Generates today's date; for substitution defs
 106 class             Set a "class" attribute on the next element
 107 role              Create a custom interpreted text role [0.3.2]
 108 default-role      Set the default interpreted text role [0.3.10]
 109 title             Set the metadata document title [0.3.10]
 110 ================  ============================================================
 111
 112 Interpreted Text Role Quick Reference
 113 =====================================
 114 See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info.
 115
 116 ================  ============================================================
 117 Role Name         Description
 118 ================  ============================================================
 119 emphasis          Equivalent to *emphasis*
 120 literal           Equivalent to ``literal`` but processes backslash escapes
 121 math              Mathematical notation (input in LaTeX format)
 122 PEP               Reference to a numbered Python Enhancement Proposal
 123 RFC               Reference to a numbered Internet Request For Comments
 124 raw               For non-reST data; cannot be used directly (see docs) [0.3.6]
 125 strong            Equivalent to **strong**
 126 sub               Subscript
 127 sup               Superscript
 128 title             Title reference (book, etc.); standard default role
 129 ================  ============================================================