reStructuredText basics#

About reStructuredText#

  • Document utility (Docutils) based on Python

  • Lightweight markup language

  • RST, reST, ReST are abbreviations. The extension is rst.

  • Document generation is possible with Sphinx.

  • Comparison with Markdown [1]

  • Output to HTML, PDF, and more is possible with Sphinx.

reStructuredText reference URL#

Section#

rst description:

#####
Title
#####
Available characters:= - ` : ' " ~ ^ _ * + # < > `
Attach below or above/below title characters

According to the style guide below:

  • # Part: with overline

  • * Chapter: with overline

  • = Section

  • - Subsection

  • ^ Subsubsection

  • Paragraph

Paragraph#

Blocks of text, or paragraphs, are separated by one or more blank lines.

Line Blocks#

Adding two spaces after a sentence like in Markdown does not create a line break. Use | at the beginning of the line instead.

Line Blocks:

| Lend us a couple of bob till Thursday.
| I'm absolutely skint.
| But I'm expecting a postal order and I can pay you back
  as soon as it comes.
| Love, Ewan.

Output:

Lend us a couple of bob till Thursday.
I’m absolutely skint.
But I’m expecting a postal order and I can pay you back as soon as it comes.
Love, Ewan.

Inline Markup#

Available Decorations for Use in Text

Bold#

Bold Text ⇒ 太文字

Code Sample#

Code Sample ⇒ コードサンプル

Formula#

\(\sqrt{16}\) ⇒ \(\sqrt{16}\)

Keyboard#

shortcut ⇒ shortcut

Literal Block#

Literal Block:

Literal Block Content

Output:#

Literal Block:

リテラルブロック内容

Inserting Code#

Use literal blocks. In Sphinx, you can use the code directive to specify details with options.

For Literal Blocks#

Example of a Literal Block:

Pythonサンプル::

  def factorial(x):
      if x == 0:
          return 1
      else:
          return x * factorial(x - 1)

Output

Python Sample:

def factorial(x):
    if x == 0:
        return 1
    else:
        return x * factorial(x - 1)

List#

Bullet Points#

Bullet Points:

* this is
* a list

  * with a nested list
  * and some subitems

* and here the parent list continues

Bullet Points (Display)

  • this is

  • a list

    • with a nested list

    • and some subitems

  • and here the parent list continues

Numbered#

Numbered:

1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.

Numbered (Display)

  1. This is a numbered list.

  2. It has two items too.

  3. This is a numbered list.

  4. It has two items too.

Term#

Term:

term1
  Definition 1.

term2
  Definition 2, paragraph 1.

  Definition 2, paragraph 2.

term3 : classifier
  Definition 3.

term4 : classifier one : classifier two
  Definition 4.

Term (Display)

term1

Definition 1.

term2

Definition 2, paragraph 1.

Definition 2, paragraph 2.

term3classifier

Definition 3.

term4classifier oneclassifier two

Definition 4.

Bullet List#

Bullet List:

:fieldname1: Field content
:fieldname12: Field content
:fieldname123: Field content
:fieldname1234: Field content

Bullet List (Display)

fieldname1:

Field content

fieldname12:

Field content

fieldname123:

Field content

fieldname1234:

Field content

Link#

External Link#

External Link1:

`Link text <https://domain.invalid/>`_

External Link2:

This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/

Internal Link#

Internal Link Representation:

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

注釈#

  • Write a footnote at the desired location as [#name]_

  • Automatic numbering with [#], explicit specification like [1] also possible

Footnote:

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

Lorem ipsum [2] dolor sit amet … [3]

Footnotes

table#

Table Fromatter#

Representing tables in plain text becomes cumbersome due to formatting, so if you are using VSCODE, plugins are convenient.

Installing Table Formatter#

How to install Table Formatter from VSCODE extension

how to use#

The format before conversion is shown as a sample
Ctrl + Shift + P and select “Table: Format Current”

table grid#

format

+
||Mon|Tue|Wed|Thu|Fri|
+=
|田中|(^^)|(xx)|(xx)|('')|(^^)|
+-
|鈴木|(^^)|(^^)|('')|(xx)|(^^)|
+

After conversion

+------+------+------+------+------+------+
|      | Mon  | Tue  | Wed  | Thu  | Fri  |
+======+======+======+======+======+======+
| 田中 | (^^) | (xx) | (xx) | ('') | (^^) |
+------+------+------+------+------+------+
| 鈴木 | (^^) | (^^) | ('') | (xx) | (^^) |
+------+------+------+------+------+------+

Actual execution

Mon

Tue

Wed

Thu

Fri

田中

(^^)

(‘’)

(^^)

鈴木

(^^)

(^^)

(‘’)

(^^)

シンプル#

format

=
Input . Output
-
A B "A or B" A_and_B
= = = =
False False False False
True False True False
=

After conversion

=====  =====  ========  =======
Input    .     Output
-----  -----  --------  -------
  A      B    "A or B"  A_and_B
=====  =====  ========  =======
False  False  False     False
True   False  True      False
=====  =====  ========  =======

Actual execution

Input

.

Output

A

B

“A or B”

A_and_B

False

False

False

False

True

False

True

False

注釈