ReStructuredText

Overview

reStructuredText 사용법 정리.

문서를 Git 이나 다른 형상관리툴로 관리하기에는 많은 어려움이 있다. 간단하게 문서 내용을 업데이트하고, 저장소 에 push 했을때, 문서의 어떤 내용이 변경되었는지 알기가 어렵다. reStructuredText 가 이에 대한 해답이 될 수도 있다.

Body Elements

Paragraphs

Syntax diagram

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

+------------------------------+
| paragraph                    |
|                              |
+------------------------------+

Bullet Lists

"*", "+", "-", "•", "‣", or "⁃" 캐릭터 뒤에 공백문자가 따라오는 경우, Bullet Lists 로 판단한다(a.k.a. "unordered" list item).

- This is the first bullet list item.  The blank line above the
  first list item is required; blank lines between list items
  (such as below this paragraph) are optional.

- This is the first paragraph in the second item in the list.

  This is the second paragraph in the second item in the list.
  The blank line above this paragraph is required.  The left edge
  of this paragraph lines up with the paragraph above, both
  indented relative to the bullet.

  - This is a sublist.  The bullet lines up with the left edge of
    the text blocks above.  A sublist is a new list so requires a
    blank line above and below.

- This is the third item of the main list.

Syntax diagram

+------+-----------------------+
| "- " | list item             |
+------| (body elements)+      |
       +-----------------------+

Enumerated Lists

다음의 캐릭터들 뒤에 공백문자가 오는 경우 Enumerated Lists(a.k.a ordered list)로 판단한다.

    arabic numerals: 1, 2, 3, ... (no upper limit).
    uppercase alphabet characters: A, B, C, ..., Z.
    lower-case alphabet characters: a, b, c, ..., z.
    uppercase Roman numerals: I, II, III, IV, ..., MMMMCMXCIX (4999).
    lowercase Roman numerals: i, ii, iii, iv, ..., mmmmcmxcix (4999).

Syntax diagram

+-------+----------------------+
| "1. " | list item            |
+-------| (body elements)+     |
        +----------------------+

Tables

Grid Tables

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | Cells may span columns.          |
+------------------------+------------+---------------------+
| body row 3             | Cells may  | - Table cells       |
+------------------------+ span rows. | - contain           |
| body row 4             |            | - body elements.    |
+------------------------+------------+---------------------+

Simple Tables

=====  =====  =======
  A      B    A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Explicit Markup Blocks

명시적 Markup 블럭은 텍스트 블럭이다. 다음과 같이 동작한다.

• 라인의 첫 부분이 ".. " 으로 시작한다(explicit markup start)
• 두번째 라인과 그 다음 라인의 시작이 같은 들여쓰기를 사용한다
• 들여쓰기가 나타나지 않는 라인까지 하나의 Markup 으로 간주한다.

즉, 명시적 Markup block 시작은 ".. "으로 시작하고 들여쓰기가 끝나는 부분에서 종료가 되는 것이다. 하지만 반드시 다음 Element 와의 사이에 빈 공백이 있어야 한다.

명시적 Markup block 은 footnotes, citation, hyperlink target, directives, substitution definition 그리고 comment 등으로 사용된다.

Footnotes

Syntax diagram

+-------+-------------------------+
| ".. " | "[" label "]" footnote  |
+-------+                         |
        | (body elements)+        |
        +-------------------------+

Auto-Numbered Footnotes

해쉬 코드("#")를 footnote 의 label 에 입력할 수 있다. label 에 해쉬 코드를 입력하게 되면, 자동으로 증가하는 footnote 번호가 입력되게 된다.

[#]_ is a reference to footnote 1, and [#]_ is a reference to footnote 2.

.. [#] This is footnote 1.
.. [#] This is footnote 2.
.. [#] This is footnote 3.

[#]_ is a reference to footnote 3.

Headers

H1, H2, H3, H4 단계로 크기 설정이 가능하다. Header 로 나타내고자 하는 글 아래에 각각의 Header 항목에 맞는 마킹을 표시한다.

H1 --  Top of Page Header
*************************

H2 -- Page Sections
===================

H3 -- Subsection
-----------------

H4 -- Subsubsection
+++++++++++++++++++

Lists

각각의 항목에 따라 자동으로 번호 및 들여쓰기 마킹이 가능하다.

* Athing.
* Another thing.

or

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

or

- Some.
- Thing.
- Different.

다음과 같은 방식으로도 가능하다.

 - A bullet list item
 - Second item
 
   - A sub item
 
 - Spacing between items creates separate lists
 
 - Third item
 
 1) An enumerated list item
 
 2) Second item
 
    a) Sub item that goes on at length and thus needs
       to be wrapped. Note the indentation that must
       match the beginning of the text, not the 
       enumerator.
 
       i) List items can even include
 
          paragraph breaks.
 
 3) Third item
 
 #) Another enumerated list item
 
 #) Second item

Tables

테이블 표현시, 다음과 같이 표현한다.

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

SIMPLE TABLE

=====  =====  ======
   Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Links

대부분의 URL 은 자동적으로 링크가 생성된다. 다른 링크를 추가하기 위해서는 '_' 연산자를 사용한다. 예를 들어, 텍스트에 하이퍼링크를 추가하기 위해서는 다음과 같이 사용하면 된다.

`Docs for this project <http://packages.python.org/an_example_pypi_project/>`_

같은 .rst 파일내에서의 링크를 위한 Anchor link 를 설정하기 위해서는 다음과 같이 사용하면 된다.

`Table of Contents`_

Images

이미지 링크시, 다음과 같이 사용하면 된다.

.. figure::  images/seat.jpg
   :align:   center

   Proof that getting rich is mostly luck.

Anchor link 를 생성하고자 한다면 다음과 같이하면 된다.

.. _is_sweaty:
.. figure::  images/sweat.jpg
   :align:   center

   Proof that getting rich is mostly luck.

이후, 다음과 같이 참조할 수 있다.

This picture is_sweaty_.

Named links

A sentence with links to Wikipedia_ and the `Linux kernel archive`_.

.. _Wikipedia: http://www.wikipedia.org/
.. _Linux kernel archive: http://www.kernel.org/

Anonymous links

 Another sentence with an `anonymous link to the Python website`__.
 
 __ https://www.python.org/

N.B.: named links and anonymous links are enclosed in grave accents (`), and not in apostrophes (').

Literal blocks

::

  some literal text

This may also be used inline at the end of a paragraph, like so::

  some more literal text

.. code:: python

<source lang="python" enclose="none">
   print("A literal block directive explicitly marked as python code")
</source>

Paragraph-level

note

API 사용시 특별히 중요한 사항들을 표시할 때 사용한다.

.. note::
   This function is not suitable for sending spam e-mails.

warning

API 사용시 특별히 조심해야 할 사항을 나타낸다.

.. warning::
   Some warning message.

versionchanged

.. versionchanged:: version

deprecated

.. deprecated:: 3.1
   Use :func:`spam` instead.

seealso

.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.

See also

• Sphinx (documentation generator)
• Comparison of documentation generators
• Comparison of notetaking software
• Comparison of document markup languages
• Setext, an old lightweight markup language (1992).
• Markdown, a widespread lightweight markup language.
• MultiMarkdown, an improved Markdown.
• Org-mode, a similar lightweight markup.
• Textile (markup language), a similar lightweight markup language to produce HTML.
• AsciiDoc, a similar lightweight markup language supporting many types of documents.
• txt2tags, another similar lightweight markup language.
• http://docutils.sourceforge.net/docs/user/rst/quickref.html - Quick reStructuredText

References

<references />