RST (reStructuredText) & Sphinx 문법 정리

 

문서 내 용어

• RST : reStructuredText
• Markdown : Markdown
• sphinx :
  • 파이썬 코드(.py)의 내용을 html로 변환해서 웹페이지로 만들어주는 툴
  • 또한, rst로 작성된 것을 HTML, PDF 등으로 변경해주는 도구
  • $ pip install sphinx 명령을 통해 설치
• index.rst : 웹 문서의 첫 페이지
• toctree : sphinx에서 index.rst를 작성 할 때 사용되는 directive

RST

글자 표현

italic 체 - * 을 양옆으로 붙임.

*텍스트*

bold 체 - ** 을 양옆으로 붙임.

**텍스트**

섹션 헤더

• 주의 : 제목의 위/아래에 들어가는 문자의 개수는 제목내용과 같거나 많아야 한다.

# 잘못된 예
title
==

# 잘된 예
title
=====

title
=======

• 헤더 레벨은 정해진 규칙은 없다(문서에서 사용되는 순서대로 레벨이 정해짐).
• 하지만, 하나의 프로젝트에는 #, *, =, -, ^, ",' 같은 특수 문자를 이용해 헤더 레벨을 정의 하여 쓰는 것이 좋다.
• 아래는 예제.

# RST                   # MarkDown

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

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

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

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

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

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

목록

일반목록

• #. 은 번호 자동생성

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

사전형 목록

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

옵션 목록

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

Directive

코드블락

• MarkDown의 ``` 으로 사용되는 부분
• code 와 code-block 은 옵션이 차이가 남, sphinx 사용시 code-block 추천
• sphinx-code-example

.. code::

    print("hello, rst!")

# Sphinx Directive 문법시 `code-block` 추천
.. code-block::

    print("hello, sphinx!")

이미지

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

inline-Directive

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

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

표

• rst는 표를 표현하는 문법이 다양
  • 데이터에 따라 적절한 문법 사용을 추천
• - 나 =의 길이는 같아야함.
  • ex

  # 가능                 # 불가능
    ========              ===
    A                     A
    ========              ==========
    data1                 data1
    ========              ========

• Grid 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
=====  =====  ======

• 리스트형식

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

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

• csv 형식

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

   A, B, C
   data1, data2, data3

• csv 파일 import 가능

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

 

 

 

 

 

수평선

• 단락 분리시 Markdown의 ------------ 부분 과 같음
• 4개 이상의 - 를 사용하여 표시
• 주의: 위, 아래 줄에 어떠한 문자가 있어서는 안됨

ABC

--------

DEF

각주(FootNote)

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

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

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

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

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

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

----

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

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

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

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

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

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

인용구

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

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

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

Hyperlink

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

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

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

• 하이퍼링크로 rst문서의 제목 링크

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

Sphinx

toctree

• sphinx-quickstart 명령을 통해서 생성된 파일중 index.rst 가 document의 첫 페이지가 된다. 이것을 toctree를 이용해서 목차를 만들 수 있다.
• 옵션(일부)
  • maxdepth is used to indicates the depth of the tree. (tree의 depth)
  • numbered adds relevant section numbers. (관련있는 섹션만 추가)
  • titlesonly adds only the main title of each document (각 document의 메인 title만 추가)
  • glob can be used to indicate that * and ? characters are used to indicate patterns. (*,? 같은 문자로 패턴사용)
  • hidden hides the toctree. It can be used to include files that do not need to be shown (e.g. a bibliography). (보여지고 싶지 않은 파일을 추가할 때 사용, .gitignore 와 비슷)

.. toctree::
   :maxdepth: 2
   :glob:

   directory1/directory2/*
   directory1/directory3/*

• toctree 문법의 옵션 참조
  • sphinx-doc: The TOC tree

참고문헌

• reStructuredText 문서
• sphinx-doc: The TOC tree
• Sphinx and RST syntax guide
• 한국어로 rst 문법 간략히 정리한 페이지