Title: Theory / Unimportant / CS / Descriptive / ReST / Bare
Tags: comment

Name: reStructuredText
Definition: easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system.
Page: https://docutils.sourceforge.io/rst.html
Abbreviation: reST
Typ: revision and reinterpretation of the StructuredText and Setext lightweight markup systems.

Name: Paragraph
Definition: A set of non-blank line separated by blank line
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Context: Rest

Instruction: multiple line
  without empty line
  with the same positive number whitespace
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: A paragraph, quoted.
Name: Block quote

Instruction: *foo*
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo in italic

Instruction: **foo**
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo in bold

Instruction: ``foo``
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo in fixed-space literal
Intuition: code

Instruction: ``character``
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: The character `character` as a literal. Not interpreted as some reST indication
Abbreviation: \character

Instruction: * foo
+ foo
- foo
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo, as a list input, with imbrication rules as for paragraph
Name: Bullet list

Instruction: i. foo
i) foo
(i) foo
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo, as the ith element of the list
Name: Enumerated list

Instruction: name
  definition
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: Introduce in a list of definition a definition for name
Name: Definition list

Instruction: ::
  any text
     all at identation level higher more than the ::
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: The text as it is, without changing it's formatting
Name: Literal blocks

Instruction: foo
=====
--------
~~~~~~~~
++++++
Page: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
Language: rest
Returns: foo as a title. If the underline is new, it's more imbricated than any underline seen. Otherwise it's the same importance level as last underline

Question: How to ensure that there is a document title
Answer: Use a title level higher than all other document title level
Page: https://www.python.org/dev/peps/pep-0343/
Context: pattern

Instruction: .. image:: url
  :property_1: value_1
  ...
  :property_n: value_n
Page: https://www.python.org/dev/peps/pep-0343/
Language: rest
Context: pattern
Returns: An image,src url and with properties values

Instruction: `foo`
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Context: pattern
Returns: foo as interpreted by default role

Instruction: foo_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Context: pattern
Returns: A link to the reference foo
Name: Reference

Instruction: foo__
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Context: pattern
Returns: With two underscores instead of one, both simple and phrase references may be anonymous (the reference text is not repeated at the target). See Hyperlink Targets.
Name: Reference

Instruction: _`foo`
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Context: pattern
Returns: A crossreference target within text. See Hyperlink Targets.
Name: Reference

Instruction: [n]_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Context: pattern
Returns: A link to the footnote labeled n
Variables: n a number
Name: Reference

Question: Inline delimiter characters
Answer: *
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Answer2: `
Answer3: |
Answer4: _

Question: Constraint on start-string
Answer: must start a text block or be immediately preceded by whitespace or any of  ' " ( [ { or <.
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Answer2: must be immediately followed by non-whitespace.
Answer3: If a start-string is immediately preceded by one of  ' " ( [ { or <, it must not be immediately followed by the corresponding character from  ' " ) ] } or >.
Answer4: An unescaped backslash preceding a start-string will disable markup recognition, except for the end-string of inline literals.

Question: Constraint on end-string
Answer: must be immediately preceded by non-whitespace.
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Answer2: must end a text block (end of document or followed by a blank line) or be immediately followed by whitespace or any of ' " . , : ; ! ? - ) ] } / \ or >.
Answer3: must be separated by at least one character from the start-string.
Answer4: An unescaped backslash preceding a end-string will disable markup recognition, except for the end-string of inline literals.

Instruction: # foo
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Returns: auto-numbered list element

Instruction: :foo:
  value
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Returns: Introduce a field named foo with value
Name: Field list

Instruction: -option  description
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Returns: Introduce an element in a list of option, with option and description
Assuming: two spaces in middle of line
Name: Option list

Instruction: | some paragraph
| where new line
| matters
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Returns: A paragraph where new line are respected
Assuming: two spaces in middle of line
Name: Line blocks
Intuition: address, adornment free list

Instruction: >>> expr
value
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Context: reST
Returns: print code expr
and its result value
Name: Doctest Blocks

Instruction: ----------
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Context: table
Returns: Horizontal separator between two cells

Instruction: left | right
cell | cell
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Context: table
Returns: Vertical separator between two cells

Instruction: +
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Context: table
Returns: both - and | to separate cells

Instruction: ======
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Context: table
Returns: cell separators where the value on top of it is a header

Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: Add a transition symbol between the previous and the next paragraph

Instruction: .. [n] footnote content
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: Add a footnote labelled n
Variables: n a number

Instruction: .. [#] content
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: Add a footnote content. The i-th iteration correspond to the ith footnote used in the text. It's label is a number automatically computed

Instruction: .. [*] content
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: Add a footnote content. The i-th iteration correspond to the ith footnote [*] used in the text. It's label change for each occurence

Instruction: [#]_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: A link to a footnote labelled by [#]. It's label is an automatically selected number

Instruction: [*]_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: A link to a footnote labelled by [#]. It's label is a symbol which change each time

Instruction: [#foo]_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: A link to a footnote labelled by [#foo]. It's label is a symbol which change each time.

Instruction: .. [#foo]
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: A footnote, autonumbered, with content content.

Instruction: [foo]_
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: The text foo, with a link to the citation labelled foo

Instruction: .. [foo] description
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: A citation, labelled foo, with description
Name: Citation

Instruction: .. _foo: url
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: reST
Returns: Introduce a label foo which is a link to url
Name: External Hyperlink Targets

Name: Fold-in hyperlink target
Definition: A hyperlink where the link is not shown.
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Intuition: Usual web page, where the computer deal with the link

Name: Call-out hyperlink target
Definition: A hyperlink where the link is shown
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Intuition: Ideal for printing

Instruction: `some text`__
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Returns: A link with text some text, to the next url introduced with __
Name: anonymous hyperlink reference

Instruction: __url
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Returns: the last anonymus hyperlink target goes to url
Name: anonymous hyperlink target
Intuition: Useful when the text is long

Instruction: |foo|
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Language: rest
Returns: Replaced by the substitution definition foo
Name: substitution reference

Instruction: .. |foo| content
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html
Meaning: content
Language: rest
Identifier: foo
Name: substitution definition

Language: rest
Instruction: .. foo
Other fields (not shown on cards):
Page: https://docutils.sourceforge.io/docs/user/rst/quickref.html

Name: The directive marker
Definition: ::
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Variables: .. foo:: bar

Name: The directive block
Definition: bar
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Variables: .. foo:: bar
Context: rst directive

Name: The directive type
Definition: foo
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Variables: .. foo:: bar
Context: reST directive

Instruction: .. foo:: bar
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Effect: Apply directive type foo with content bar
Context: reST
Name: A directive
Intuition: a general-purpose extension mechanism, a way of adding support for new constructs without adding new syntax

Name: An admonition
Definition: specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements.
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Context: reST
Example: .. DANGER::
   Beware killer rabbits!
+------------------------+
|        !DANGER!        |
|                        |
| Beware killer rabbits! |
+------------------------+
Intuition: an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type

Instruction: .. topic:: title
  content
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: introduce a block quote with title and content
Intuition: some self contained content

Instruction: .. sidebar:: title
  content of the side bar
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: introduce a side bare with title and content
Intuition: miniature, parallel documents that occur inside other documents, providing related or reference material.

Instruction: .. parsed-literal::
  some paragraph
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: todo?

Instruction: .. code:: language
  some paragraph
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: show some paragraph as code content with syntax highlighting according to language

Instruction: .. math_block::
  some paragraph
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: show some paragraph as latex math

Instruction: .. rubric::
  some paragraph
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: inserts a "rubric" element into the document tree. A rubric is like an informal heading that doesn't correspond to the document's structure.

Instruction: .. epigraph::
  quote
  -- author
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: inserts an epigraph from author with content quote

Instruction: .. highlight::
  content
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Returns: summarize content, the main points of a document or section, often consisting of a list.

Typ: Directive
Meaning: An abstract directive, taking options and returning a list of nodes to insert into the document tree
Page: https://docutils.sourceforge.io/docs/ref/rst/directives.html
Language: reST
Library: docutils.parsers.rst

Instruction: self.error('foo')
Page: https://docutils.sourceforge.io/docs/howto/rst-directives.html
Meaning: Stop evaluating this directive, and replace it by error message foo
Language: reST

Instruction: :role:`foo`
Page: https://docutils.sourceforge.io/docs/ref/rst/roles.html
Language: reST
Returns: foo, as interpreted by role