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