ReStructuredText

lastmod 2025-04-15created 2020-01-0957 edits

reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation.

It is part of the Docutils project of the Python Doc-SIG (Documentation Special Interest Group), aimed at creating a set of tools for Python similar to Javadoc for Java or Plain Old Documentation (pod) for Perl. Docutils can extract comments and information from Python programs, and format them into various forms of program documentation.

In this sense, reStructuredText is a lightweight markup language designed to be both (a) processable by documentation-processing software such as Docutils, and (b) easily readable by human programmers who are reading and writing Python source code.

Basic Syntax

[Recommended] FWANI :: RST (reStructuredText) & Sphinx syntax summary - Not much, but explained briefly and clearly.

*이텔릭체*
**볼드체**
`해석 된 텍스트`
``Code Text``
reference_
`구문 참조`_
anonymous__
_`inline internal target`
|substitution reference|
footnote reference [1]_
citation reference [CIT2002]_
http://docutils.sf.net/

`해석 된 텍스트` The rendering and meaning of interpreted text depend on the domain or application.

Special characters (Escaping with Backslashes)

reStructuredText uses the backslash (\) to ignore the special meaning given to markup characters and get the literal character itself. To get a literal backslash, use an escaped backslash (\\). For example:

*escape* ``with`` "\"
\*escape* \``with`` "\\"

Links to External Web Pages

To link to an external web page, use the following syntax:

`Link text <link URL>`_

For example:

`CNN <http://cnn.com>`_

You can also separate the link and the target definition. For example:

Get the latest news at `CNN`_.

.. _CNN: http://cnn.com/

==============
Section Title           # Section Title
==============

--------------
Section Title           ## Section Title
--------------

Section Title           ### Section Title
=============

Section Title           #### Section Title
-------------

Section Title           ##### Section Title
\`````````````

Section Title           ###### Section Title
'''''''''''''

* ``#`` with overline, for parts
* ``*`` with overline, for chapters
* ``=``, for sections
* ``-``, for subsections
* ``^``, for subsubsections
* ``"``, for paragraphs

Blocks

A paragraph containing only two colons indicates
the following indented or quoted text is a literal
block or quoted text is a literal block.

::

  Whitespace, newlines, blank lines, and  all kinds of
  markup (like *this* or \this) is preserved here.

You can also tack the ``::`` at the end of a
paragraph::

   It's very convenient to use this form.

Per-line quoting can also be used for unindented
blocks::

> Useful for quotes from email and
> for Haskell literate programming.

| Line blocks are useful for addresses,
| verse, and adornment-free lists.
|
| Each new line begins with a
| vertical bar ("|").
|     Line breaks and initial indents
|     are preserved.
| Continuation lines are wrapped
  portions of long lines; they begin
  with spaces in place of vertical bars.

Block quotes are just:

    Indented paragraphs,

        and they may nest.

Doctest blocks are interactive
Python sessions. They begin with
"``>>>``" and end with a blank line.

>>> print "This is a doctest block."
This is a doctest block.

Lists

Ordered list

1. 목록입니다.
2. 목록입니다.
#. 목록입니다.

Unordered list

* Item 1.
* Item 2.
* Item 3.

Nested lists

#. Step 1.

    * Item 1.

    * Item 2.

#. Step 2.

or

* Item 1.

  #. Step 1.

  #. Step 2.

* Item 2.

and so on...

Code in lists

#. Step 1. Example:

    .. code-block:: bash

      Example code

#. Step 2.

Definition list

들여쓰기 없음 (1)
    네 칸을 띄고 쓰면 들여쓰기 (2)
        네 칸씩 들여쓰기 가능 (3)
    네 칸을 띄고 쓰면 들여쓰기 (2)
들여쓰기 없음 (1)

Option list

-a          옵션 a 설명
-b file     옵션 b 설명
--opt_a     옵션 opt_a 설명

Images

Inserting an image

.. image:: 이미지 파일 경로
    :height: 250
    :width: 250
    :scale: 50
    :alt: 이미지 설명

Inline insertion

문장 중간에 |이모티콘| 같은 이미지를 넣을 수 있습니다.

.. |이모티콘| image:: 이모티콘경로

Table

Inserting a table

The - or = lengths must match.

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

List-style table

.. list-table::
   :header-rows: 1

   * - A
     - B
     - C
   * - data1
     - data2
     - data3

CSV table

.. csv-table:: 테이블 타이틀 (없어도 됨)
   :header-rows: 1

   A, B, C
   data1, data2, data3

It can be loaded from a file:

.. csv-table:: Table Title
   :file: CSV file path
   :widths: 30, 70
   :header-rows: 1

Horizontal rule

Written with 4 or more -
The lines above and below must not contain any characters

ABC

--------

DEF

Footnotes (FootNote)

1. 번호를 명시적으로 사용 [5]_

.. [5] 각주 5번에 대한 노트부분
   엔터를 해서 사용해도 결과는 한 줄

결과 부분-----
[5] 각주 5번에 대한 노트부분 엔터를 해서 사용해도 결과는 한 줄

Auto-numbering:

2. 번호를 자동으로 매겨주는 각주 방법, [#]_ 과 [#]_

.. [#] 첫번째 각주
.. [#] 두번째 각주

결과 부분-----
[1] 첫번째 각주
[2] 두번째 각주

----

3. 이걸 [#third] 나 [#fourth] 처럼 명시적인 이름을 부여할 수 있음
   결과는 위에 [#] 과 동일하게 번호를 순차적으로 매겨줌

.. [#third] 세번째 각주
.. [#fourth] 네번째 각주

결과 부분-----
[3] 세번째 각주
[4] 네번째 각주

Auto-symbol footnotes:

4. Auto-symbol 각주 방법, 각주의 심볼이 숫자가 아닐 수 있음 [*]_ 과 [*]_

.. [*] 첫번째
.. [*] 두번째

결과 부분-----
[*]    첫번째
[†]    두번째

Citations

인용구는 대괄호와 _로 구성, [인용구]_

.. [인용구] 인용문구 예시입니다.

결과 부분-----
[인용구] 인용문구 예시입니다.

Link

Linking to a section in the same document

You can link text to a heading in another part of the document with the :ref: command, using the heading text as the parameter.

For example, this text in another part of this document links to the following section.

:ref:`Cross-References to Locations in the Same Document`

Use Custom Link Text

For internal links that use text other than the heading for the section that you’re linking to, use :ref:`custom text<Heading Text>` syntax, as in the following example.

Learn how to :ref:`link to a different section<Cross-References to Locations in the Same Document>`.

External site links

하이퍼링크 사용법 1번, 파이썬_

.. _파이썬: http://www.python.org/

Inline link:

하이퍼링크 사용법 2번, `파이썬 <http://www.python.org/>`_

Linking to a heading in the document

Title 라인
=========
이것은 `Title 라인`_ 을 하이퍼링크 하는방법 입니다.

Custom anchors

If a project has two sections with the same title, a link to either of them causes a build error because Sphinx doesn't know which section to link to.

In this case, you can create a custom anchor directly above the heading and link to it instead of the heading itself. For example, if each part of the documentation has a section called Overview, you need to add a more specific anchor above the section title.

.. _RST Overview:

Overview
**********

RST Overview content


.. _Sphinx Overview:

Overview
*********

Sphinx Overview content

In a :ref: command, you then use the anchor text. For example:

This is a link to the RST Overview: :ref:`RST Overview`

This is a link to the Sphinx Overview: :ref:`Sphinx Overview`

Note

.. note::
   This is note text. Use a note for information you want the user to
   pay particular attention to.

   If note text runs over a line, make sure the lines wrap and are indented to
   the same level as the note tag. If formatting is incorrect, part of the note
   might not render in the HTML output.

   Notes can have more than one paragraph. Successive paragraphs must
   indent to the same level as the rest of the note.

Warning

.. warning::
    This is warning text. Use a warning for information the user must
    understand to avoid negative consequences.

    Warnings are formatted in the same way as notes. In the same way,
    lines must be broken and indented under the warning tag.

The TOC tree

The TOC tree — Sphinx 1.5.6 documentation

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric

:maxdepth: 2 Setting this parameter to 2 or higher includes other levels in the indented list.
:numbered: Automatically generates numbered topics and sections.

Code Block

You can add a code block.

.. code-block:: javascript
    :linenos:
    :emphasize-lines: 8,10,16

    code . . .

:linenos:: Adds line numbers.
:emphasize-lines: 8,10,16: Highlight Lines

Adding line breaks

Stackoverflow - How do I create a new line with reStructuredText?

Add the following to a global file such as global.rst.

.. |br| raw:: html

  <br/>

Then insert |br| wherever you want.

Glossary

.. glossary::

    Sphinx
      Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It was originally created for the Python documentation, and it has excellent facilities for the documentation of software projects in a range of languages.

    RST
      |RST| is an easy-to-read, what-you-see-is-what-you-get plain text markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. |RST| is designed for extensibility for specific application domains. The |RST| parser is a component of Docutils.

    Sublime Text
      Sublime Text is a sophisticated text editor for code, markup and prose. You'll love the slick user interface, extraordinary features and amazing performance.

Link a Term to its a Glossary Entry

When a glossary term is used in text, you can link it to its definition with the :term: role. For example, to link the term Sphinx to its definition, use the following syntax:

:term:`Sphinx`

The term specified must exactly match a term in Glossary directive.

You can link to a term in the glossary while showing different text in the topic by including the term in angle brackets. For example:

:term:`reStructuredText<RST>`

The term in angle brackets must exactly match a term in the glossary. The text before the angle brackets is what users see on the page.

Contents directives

.. contents:: a title for the contents
    :depth: 2

:depth: indicates the max section depth to be shown in the contents

Conditional text output

Sphinx supports conditional text. That is, you can specify that some content is shown only to its intended audience. You can then build different versions of the project for different audiences.

To restrict the visibility of specific content, indent that content under the .. only:: directive. For example, to specify that some content is available only to internal users, use the following.

.. only:: Internal

  Content to be included only in the internal version of the document.

LaTeX

The extension to be added is the pngmath from sphinx:

extensions.append('sphinx.ext.pngmath')

Add inline as follows:

:math:`\alpha > \beta`

Add a block as follows:

.. math::

    n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k

Useful extensions

In the special file called conf.py, there is a variable called extensions. You can add extension in this variable. For instance:

extensions = [-
    'easydev.copybutton',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.coverage',
    'sphinx.ext.graphviz',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.pngmath',
    'sphinx.ext.ifconfig',
    'matplotlib.sphinxext.only_directives',
    'matplotlib.sphinxext.plot_directive',
 ]

Favorite site

Wikipedia (en) ReStructuredText

References

Restructured_Text_and_Sphinx_CheatSheet_-Sphinx_and_RST_syntax_guide-_0.9.3.pdf ↩

author Zer0 sitemap