ABOUT ME

-

Today
-
Yesterday
-
Total
-
  • RST (reStructuredText) & Sphinx 문법 정리
    Programming Language/Python 2019. 12. 9. 17:59
    반응형

     

    문서 내 용어

    • 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의 ``` 으로 사용되는 부분
    • codecode-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/*

    참고문헌

    반응형

    댓글

Designed by Tistory.