third-party/codemirror-3.15/mode/rst/index.html

   1 <!doctype html>
   2 <html>
   3   <head>
   4     <meta charset="utf-8">
   5     <title>CodeMirror: reStructuredText mode</title>
   6     <link rel="stylesheet" href="../../lib/codemirror.css">
   7     <script src="../../lib/codemirror.js"></script>
   8     <script src="rst.js"></script>
   9     <style type="text/css">.CodeMirror {border-top: 1px solid black; border-bottom: 1px solid black;}</style>
  10     <link rel="stylesheet" href="../../doc/docs.css">
  11   </head>
  12   <body>
  13     <h1>CodeMirror: reStructuredText mode</h1>
  14
  15 <form><textarea id="code" name="code">
  16 .. This is an excerpt from Sphinx documentation: http://sphinx.pocoo.org/_sources/rest.txt
  17
  18 .. highlightlang:: rest
  19
  20 .. _rst-primer:
  21
  22 reStructuredText Primer
  23 =======================
  24
  25 This section is a brief introduction to reStructuredText (reST) concepts and
  26 syntax, intended to provide authors with enough information to author documents
  27 productively.  Since reST was designed to be a simple, unobtrusive markup
  28 language, this will not take too long.
  29
  30 .. seealso::
  31
  32    The authoritative `reStructuredText User Documentation
  33    &lt;http://docutils.sourceforge.net/rst.html&gt;`_.  The "ref" links in this
  34    document link to the description of the individual constructs in the reST
  35    reference.
  36
  37
  38 Paragraphs
  39 ----------
  40
  41 The paragraph (:duref:`ref &lt;paragraphs&gt;`) is the most basic block in a reST
  42 document.  Paragraphs are simply chunks of text separated by one or more blank
  43 lines.  As in Python, indentation is significant in reST, so all lines of the
  44 same paragraph must be left-aligned to the same level of indentation.
  45
  46
  47 .. _inlinemarkup:
  48
  49 Inline markup
  50 -------------
  51
  52 The standard reST inline markup is quite simple: use
  53
  54 * one asterisk: ``*text*`` for emphasis (italics),
  55 * two asterisks: ``**text**`` for strong emphasis (boldface), and
  56 * backquotes: ````text```` for code samples.
  57
  58 If asterisks or backquotes appear in running text and could be confused with
  59 inline markup delimiters, they have to be escaped with a backslash.
  60
  61 Be aware of some restrictions of this markup:
  62
  63 * it may not be nested,
  64 * content may not start or end with whitespace: ``* text*`` is wrong,
  65 * it must be separated from surrounding text by non-word characters.  Use a
  66   backslash escaped space to work around that: ``thisis\ *one*\ word``.
  67
  68 These restrictions may be lifted in future versions of the docutils.
  69
  70 reST also allows for custom "interpreted text roles"', which signify that the
  71 enclosed text should be interpreted in a specific way.  Sphinx uses this to
  72 provide semantic markup and cross-referencing of identifiers, as described in
  73 the appropriate section.  The general syntax is ``:rolename:`content```.
  74
  75 Standard reST provides the following roles:
  76
  77 * :durole:`emphasis` -- alternate spelling for ``*emphasis*``
  78 * :durole:`strong` -- alternate spelling for ``**strong**``
  79 * :durole:`literal` -- alternate spelling for ````literal````
  80 * :durole:`subscript` -- subscript text
  81 * :durole:`superscript` -- superscript text
  82 * :durole:`title-reference` -- for titles of books, periodicals, and other
  83   materials
  84
  85 See :ref:`inline-markup` for roles added by Sphinx.
  86
  87
  88 Lists and Quote-like blocks
  89 ---------------------------
  90
  91 List markup (:duref:`ref &lt;bullet-lists&gt;`) is natural: just place an asterisk at
  92 the start of a paragraph and indent properly.  The same goes for numbered lists;
  93 they can also be autonumbered using a ``#`` sign::
  94
  95    * This is a bulleted list.
  96    * It has two items, the second
  97      item uses two lines.
  98
  99    1. This is a numbered list.
 100    2. It has two items too.
 101
 102    #. This is a numbered list.
 103    #. It has two items too.
 104
 105
 106 Nested lists are possible, but be aware that they must be separated from the
 107 parent list items by blank lines::
 108
 109    * this is
 110    * a list
 111
 112      * with a nested list
 113      * and some subitems
 114
 115    * and here the parent list continues
 116
 117 Definition lists (:duref:`ref &lt;definition-lists&gt;`) are created as follows::
 118
 119    term (up to a line of text)
 120       Definition of the term, which must be indented
 121
 122       and can even consist of multiple paragraphs
 123
 124    next term
 125       Description.
 126
 127 Note that the term cannot have more than one line of text.
 128
 129 Quoted paragraphs (:duref:`ref &lt;block-quotes&gt;`) are created by just indenting
 130 them more than the surrounding paragraphs.
 131
 132 Line blocks (:duref:`ref &lt;line-blocks&gt;`) are a way of preserving line breaks::
 133
 134    | These lines are
 135    | broken exactly like in
 136    | the source file.
 137
 138 There are also several more special blocks available:
 139
 140 * field lists (:duref:`ref &lt;field-lists&gt;`)
 141 * option lists (:duref:`ref &lt;option-lists&gt;`)
 142 * quoted literal blocks (:duref:`ref &lt;quoted-literal-blocks&gt;`)
 143 * doctest blocks (:duref:`ref &lt;doctest-blocks&gt;`)
 144
 145
 146 Source Code
 147 -----------
 148
 149 Literal code blocks (:duref:`ref &lt;literal-blocks&gt;`) are introduced by ending a
 150 paragraph with the special marker ``::``.  The literal block must be indented
 151 (and, like all paragraphs, separated from the surrounding ones by blank lines)::
 152
 153    This is a normal text paragraph. The next paragraph is a code sample::
 154
 155       It is not processed in any way, except
 156       that the indentation is removed.
 157
 158       It can span multiple lines.
 159
 160    This is a normal text paragraph again.
 161
 162 The handling of the ``::`` marker is smart:
 163
 164 * If it occurs as a paragraph of its own, that paragraph is completely left
 165   out of the document.
 166 * If it is preceded by whitespace, the marker is removed.
 167 * If it is preceded by non-whitespace, the marker is replaced by a single
 168   colon.
 169
 170 That way, the second sentence in the above example's first paragraph would be
 171 rendered as "The next paragraph is a code sample:".
 172
 173
 174 .. _rst-tables:
 175
 176 Tables
 177 ------
 178
 179 Two forms of tables are supported.  For *grid tables* (:duref:`ref
 180 &lt;grid-tables&gt;`), you have to "paint" the cell grid yourself.  They look like
 181 this::
 182
 183    +------------------------+------------+----------+----------+
 184    | Header row, column 1   | Header 2   | Header 3 | Header 4 |
 185    | (header rows optional) |            |          |          |
 186    +========================+============+==========+==========+
 187    | body row 1, column 1   | column 2   | column 3 | column 4 |
 188    +------------------------+------------+----------+----------+
 189    | body row 2             | ...        | ...      |          |
 190    +------------------------+------------+----------+----------+
 191
 192 *Simple tables* (:duref:`ref &lt;simple-tables&gt;`) are easier to write, but
 193 limited: they must contain more than one row, and the first column cannot
 194 contain multiple lines.  They look like this::
 195
 196    =====  =====  =======
 197    A      B      A and B
 198    =====  =====  =======
 199    False  False  False
 200    True   False  False
 201    False  True   False
 202    True   True   True
 203    =====  =====  =======
 204
 205
 206 Hyperlinks
 207 ----------
 208
 209 External links
 210 ^^^^^^^^^^^^^^
 211
 212 Use ```Link text &lt;http://example.com/&gt;`_`` for inline web links.  If the link
 213 text should be the web address, you don't need special markup at all, the parser
 214 finds links and mail addresses in ordinary text.
 215
 216 You can also separate the link and the target definition (:duref:`ref
 217 &lt;hyperlink-targets&gt;`), like this::
 218
 219    This is a paragraph that contains `a link`_.
 220
 221    .. _a link: http://example.com/
 222
 223
 224 Internal links
 225 ^^^^^^^^^^^^^^
 226
 227 Internal linking is done via a special reST role provided by Sphinx, see the
 228 section on specific markup, :ref:`ref-role`.
 229
 230
 231 Sections
 232 --------
 233
 234 Section headers (:duref:`ref &lt;sections&gt;`) are created by underlining (and
 235 optionally overlining) the section title with a punctuation character, at least
 236 as long as the text::
 237
 238    =================
 239    This is a heading
 240    =================
 241
 242 Normally, there are no heading levels assigned to certain characters as the
 243 structure is determined from the succession of headings.  However, for the
 244 Python documentation, this convention is used which you may follow:
 245
 246 * ``#`` with overline, for parts
 247 * ``*`` with overline, for chapters
 248 * ``=``, for sections
 249 * ``-``, for subsections
 250 * ``^``, for subsubsections
 251 * ``"``, for paragraphs
 252
 253 Of course, you are free to use your own marker characters (see the reST
 254 documentation), and use a deeper nesting level, but keep in mind that most
 255 target formats (HTML, LaTeX) have a limited supported nesting depth.
 256
 257
 258 Explicit Markup
 259 ---------------
 260
 261 "Explicit markup" (:duref:`ref &lt;explicit-markup-blocks&gt;`) is used in reST for
 262 most constructs that need special handling, such as footnotes,
 263 specially-highlighted paragraphs, comments, and generic directives.
 264
 265 An explicit markup block begins with a line starting with ``..`` followed by
 266 whitespace and is terminated by the next paragraph at the same level of
 267 indentation.  (There needs to be a blank line between explicit markup and normal
 268 paragraphs.  This may all sound a bit complicated, but it is intuitive enough
 269 when you write it.)
 270
 271
 272 .. _directives:
 273
 274 Directives
 275 ----------
 276
 277 A directive (:duref:`ref &lt;directives&gt;`) is a generic block of explicit markup.
 278 Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes
 279 heavy use of it.
 280
 281 Docutils supports the following directives:
 282
 283 * Admonitions: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`,
 284   :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`,
 285   :dudir:`tip`, :dudir:`warning` and the generic :dudir:`admonition`.
 286   (Most themes style only "note" and "warning" specially.)
 287
 288 * Images:
 289
 290   - :dudir:`image` (see also Images_ below)
 291   - :dudir:`figure` (an image with caption and optional legend)
 292
 293 * Additional body elements:
 294
 295   - :dudir:`contents` (a local, i.e. for the current file only, table of
 296     contents)
 297   - :dudir:`container` (a container with a custom class, useful to generate an
 298     outer ``&lt;div&gt;`` in HTML)
 299   - :dudir:`rubric` (a heading without relation to the document sectioning)
 300   - :dudir:`topic`, :dudir:`sidebar` (special highlighted body elements)
 301   - :dudir:`parsed-literal` (literal block that supports inline markup)
 302   - :dudir:`epigraph` (a block quote with optional attribution line)
 303   - :dudir:`highlights`, :dudir:`pull-quote` (block quotes with their own
 304     class attribute)
 305   - :dudir:`compound` (a compound paragraph)
 306
 307 * Special tables:
 308
 309   - :dudir:`table` (a table with title)
 310   - :dudir:`csv-table` (a table generated from comma-separated values)
 311   - :dudir:`list-table` (a table generated from a list of lists)
 312
 313 * Special directives:
 314
 315   - :dudir:`raw` (include raw target-format markup)
 316   - :dudir:`include` (include reStructuredText from another file)
 317     -- in Sphinx, when given an absolute include file path, this directive takes
 318     it as relative to the source directory
 319   - :dudir:`class` (assign a class attribute to the next element) [1]_
 320
 321 * HTML specifics:
 322
 323   - :dudir:`meta` (generation of HTML ``&lt;meta&gt;`` tags)
 324   - :dudir:`title` (override document title)
 325
 326 * Influencing markup:
 327
 328   - :dudir:`default-role` (set a new default role)
 329   - :dudir:`role` (create a new role)
 330
 331   Since these are only per-file, better use Sphinx' facilities for setting the
 332   :confval:`default_role`.
 333
 334 Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and
 335 :dudir:`footer`.
 336
 337 Directives added by Sphinx are described in :ref:`sphinxmarkup`.
 338
 339 Basically, a directive consists of a name, arguments, options and content. (Keep
 340 this terminology in mind, it is used in the next chapter describing custom
 341 directives.)  Looking at this example, ::
 342
 343    .. function:: foo(x)
 344                  foo(y, z)
 345       :module: some.module.name
 346
 347       Return a line of text input from the user.
 348
 349 ``function`` is the directive name.  It is given two arguments here, the
 350 remainder of the first line and the second line, as well as one option
 351 ``module`` (as you can see, options are given in the lines immediately following
 352 the arguments and indicated by the colons).  Options must be indented to the
 353 same level as the directive content.
 354
 355 The directive content follows after a blank line and is indented relative to the
 356 directive start.
 357
 358
 359 Images
 360 ------
 361
 362 reST supports an image directive (:dudir:`ref &lt;image&gt;`), used like so::
 363
 364    .. image:: gnu.png
 365       (options)
 366
 367 When used within Sphinx, the file name given (here ``gnu.png``) must either be
 368 relative to the source file, or absolute which means that they are relative to
 369 the top source directory.  For example, the file ``sketch/spam.rst`` could refer
 370 to the image ``images/spam.png`` as ``../images/spam.png`` or
 371 ``/images/spam.png``.
 372
 373 Sphinx will automatically copy image files over to a subdirectory of the output
 374 directory on building (e.g. the ``_static`` directory for HTML output.)
 375
 376 Interpretation of image size options (``width`` and ``height``) is as follows:
 377 if the size has no unit or the unit is pixels, the given size will only be
 378 respected for output channels that support pixels (i.e. not in LaTeX output).
 379 Other units (like ``pt`` for points) will be used for HTML and LaTeX output.
 380
 381 Sphinx extends the standard docutils behavior by allowing an asterisk for the
 382 extension::
 383
 384    .. image:: gnu.*
 385
 386 Sphinx then searches for all images matching the provided pattern and determines
 387 their type.  Each builder then chooses the best image out of these candidates.
 388 For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf`
 389 and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose
 390 the former, while the HTML builder would prefer the latter.
 391
 392 .. versionchanged:: 0.4
 393    Added the support for file names ending in an asterisk.
 394
 395 .. versionchanged:: 0.6
 396    Image paths can now be absolute.
 397
 398
 399 Footnotes
 400 ---------
 401
 402 For footnotes (:duref:`ref &lt;footnotes&gt;`), use ``[#name]_`` to mark the footnote
 403 location, and add the footnote body at the bottom of the document after a
 404 "Footnotes" rubric heading, like so::
 405
 406    Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
 407
 408    .. rubric:: Footnotes
 409
 410    .. [#f1] Text of the first footnote.
 411    .. [#f2] Text of the second footnote.
 412
 413 You can also explicitly number the footnotes (``[1]_``) or use auto-numbered
 414 footnotes without names (``[#]_``).
 415
 416
 417 Citations
 418 ---------
 419
 420 Standard reST citations (:duref:`ref &lt;citations&gt;`) are supported, with the
 421 additional feature that they are "global", i.e. all citations can be referenced
 422 from all files.  Use them like so::
 423
 424    Lorem ipsum [Ref]_ dolor sit amet.
 425
 426    .. [Ref] Book or article reference, URL or whatever.
 427
 428 Citation usage is similar to footnote usage, but with a label that is not
 429 numeric or begins with ``#``.
 430
 431
 432 Substitutions
 433 -------------
 434
 435 reST supports "substitutions" (:duref:`ref &lt;substitution-definitions&gt;`), which
 436 are pieces of text and/or markup referred to in the text by ``|name|``.  They
 437 are defined like footnotes with explicit markup blocks, like this::
 438
 439    .. |name| replace:: replacement *text*
 440
 441 or this::
 442
 443    .. |caution| image:: warning.png
 444                 :alt: Warning!
 445
 446 See the :duref:`reST reference for substitutions &lt;substitution-definitions&gt;`
 447 for details.
 448
 449 If you want to use some substitutions for all documents, put them into
 450 :confval:`rst_prolog` or put them into a separate file and include it into all
 451 documents you want to use them in, using the :rst:dir:`include` directive.  (Be
 452 sure to give the include file a file name extension differing from that of other
 453 source files, to avoid Sphinx finding it as a standalone document.)
 454
 455 Sphinx defines some default substitutions, see :ref:`default-substitutions`.
 456
 457
 458 Comments
 459 --------
 460
 461 Every explicit markup block which isn't a valid markup construct (like the
 462 footnotes above) is regarded as a comment (:duref:`ref &lt;comments&gt;`).  For
 463 example::
 464
 465    .. This is a comment.
 466
 467 You can indent text after a comment start to form multiline comments::
 468
 469    ..
 470       This whole indented block
 471       is a comment.
 472
 473       Still in the comment.
 474
 475
 476 Source encoding
 477 ---------------
 478
 479 Since the easiest way to include special characters like em dashes or copyright
 480 signs in reST is to directly write them as Unicode characters, one has to
 481 specify an encoding.  Sphinx assumes source files to be encoded in UTF-8 by
 482 default; you can change this with the :confval:`source_encoding` config value.
 483
 484
 485 Gotchas
 486 -------
 487
 488 There are some problems one commonly runs into while authoring reST documents:
 489
 490 * **Separation of inline markup:** As said above, inline markup spans must be
 491   separated from the surrounding text by non-word characters, you have to use a
 492   backslash-escaped space to get around that.  See `the reference
 493   &lt;http://docutils.sf.net/docs/ref/rst/restructuredtext.html#inline-markup&gt;`_
 494   for the details.
 495
 496 * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
 497   possible.
 498
 499
 500 .. rubric:: Footnotes
 501
 502 .. [1] When the default domain contains a :rst:dir:`class` directive, this directive
 503        will be shadowed.  Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.
 504 </textarea></form>
 505
 506     <script>
 507       var editor = CodeMirror.fromTextArea(document.getElementById("code"), {
 508         lineNumbers: true,
 509       });
 510     </script>
 511     <p>
 512         The <code>python</code> mode will be used for highlighting blocks
 513         containing Python/IPython terminal sessions: blocks starting with
 514         <code>&gt;&gt;&gt;</code> (for Python) or <code>In [num]:</code> (for
 515         IPython).
 516
 517         Further, the <code>stex</code> mode will be used for highlighting
 518         blocks containing LaTex code.
 519     </p>
 520
 521     <p><strong>MIME types defined:</strong> <code>text/x-rst</code>.</p>
 522   </body>
 523 </html>
 524