CodeMirror: reStructuredText mode

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
.. This is an excerpt from Sphinx documentation: http://sphinx.pocoo.org/_sources/rest.txt
 
.. 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::
 

The reStructuredText mode supports one configuration parameter:

verbatim (string)
A name or MIME type of a mode that will be used for highlighting verbatim blocks. By default, reStructuredText mode uses uniform color for whole block of verbatim text if no mode is given.

If python mode is available, it will be used for highlighting blocks containing Python/IPython terminal sessions (blocks starting with >>> (for Python) or In [num]: (for IPython).

MIME types defined: text/x-rst.