ReStructuredText

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.

기본 Syntax

[추천] FWANI :: RST (reStructuredText) & Sphinx 문법 정리 - 많지 않지만 간략하고 보기 좋게 설명.

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

`해석 된 텍스트` 해석 된 텍스트의 렌더링 및 의미는 도메인 또는 응용 프로그램에 따라 다릅니다.

특수 문자 (Escaping with Backslashes)

reStructuredText는 백 슬래시 (\)를 사용하여 마크 업 문자에 주어진 특수한 의미를 무시하고 리터럴 문자 자체를 가져옵니다. 리터럴 백 슬래시를 얻으려면 이스케이프 된 백 슬래시 (\\)를 사용하십시오. 예를 들면:

*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

블록

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.

목록

순서 있는 목록

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

순서 없는 목록

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

목록의 하위 목록

#. Step 1.

    * Item 1.

    * Item 2.

#. Step 2.

또는

* Item 1.

  #. Step 1.

  #. Step 2.

* Item 2.

등등...

목록의 코드

#. Step 1. Example:

    .. code-block:: bash

      Example code

#. Step 2.

사전형 목록

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

옵션 목록

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

이미지

이미지 삽입

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

인라인(inline) 삽입

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

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

표 (Table)

표(Table) 삽입

- 또는 =의 길이는 같아야 한다.

+------------+------------+-----------+
| 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. |
+------------+------------+-----------+

리스트(Table) 형식 테이블

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

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

CSV 테이블

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

   A, B, C
   data1, data2, data3

파일로 부터 받아올 수 있다:

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

수평선

4개 이상의 - 를 사용하여 표시
위, 아래 줄에 어떠한 문자가 있어서는 안됨

ABC

--------

DEF

각주 (FootNote)

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

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

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

자동 번호:

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

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

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

----

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

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

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

자동 심볼 각주:

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

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

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

인용구

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

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

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

링크 (Link)

동일한 문서의 섹션에 대한 링크

제목 텍스트를 매개 변수로 사용하여 :ref: 명령을 사용하여 문서의 다른 부분에있는 제목으로 텍스트를 링크 할 수 있습니다.

예를 들어이 문서의 다른 부분에있는이 텍스트는 다음 섹션으로 연결됩니다.

: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>`.

외부 사이트 링크

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

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

인라인 링크:

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

문서의 제목 링크

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

커스텀 앵커

프로젝트에 제목이 같은 섹션이 두 개있는 경우 두 섹션 중 하나에 대한 링크가 있으면 Sphinx가 링크 할 섹션을 모르기 때문에 빌드 오류가 발생합니다.

이 경우 제목 자체 대신 제목 바로 위에 사용자 지정 앵커를 만들고 링크 할 수 있습니다. 예를 들어 문서의 각 부분에 개요라는 섹션이있는 경우 섹션 제목 위에보다 구체적인 앵커를 추가해야합니다.

.. _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::
   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::
    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 매개 변수를 2 이상으로 설정하여 들여 쓰기 목록에 다른 레벨을 포함 할 수 있습니다.
:numbered: 번호가 매겨진 주제 및 섹션을 자동으로 생성 할 수 있습니다.

Code Block

코드 블럭을 추가할 수 있다.

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

    code . . .

:linenos:: 라인 넘버를 첨부한다.
:emphasize-lines: 8,10,16: Highlight Lines

개행 추가

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

다음 내용을 global.rst 와 같은 전역 파일에 추가한다.

.. |br| raw:: html

  <br/>

이 후, |br|을 원하는 위치에 삽입하면 된다.

용어집

.. 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

조건부 텍스트 출력

Sphinx는 조건부 텍스트를 지원합니다. 즉, 일부 콘텐츠가 의도 된 청중에게만 표시되도록 지정할 수 있습니다. 그런 다음 다양한 청중을 위해 다양한 버전의 프로젝트를 구축 할 수 있습니다.

특정 콘텐츠의 가시성을 제한하려면 .. only:: 지시문 아래에서 해당 콘텐츠를 들여 쓰십시오. 예를 들어 일부 콘텐츠가 내부 사용자 만 사용할 수 있도록 지정하려면 다음을 사용합니다.

.. 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')

다음과 같이 인라인 추가:

:math:`\alpha > \beta`

다음과 같이 블록 추가:

.. 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 ↩