rST / Sphinx 기초

본 프로젝트는 reStructuredText(rST)와 Sphinx 로 문서를 작성합니다. 이 문서는 처음 기여하는 분을 위한 최소한의 기초를 정리합니다.

왜 rST/Sphinx 인가

• OpenStack 문서 생태계의 표준 (OpenStack 문서 관례)

• toctree 기반의 다중 페이지 구조화에 강함

• 교차 참조(cross-reference), 용어집(glossary), admonition 등 학습 경로형 문서에 적합한 기능 제공

참고

Kubernetes 공식 문서는 Hugo/Markdown 기반입니다. 두 생태계의 차이는 Kubernetes 문서 관례 에서 다룹니다.

제목과 섹션

제목은 밑줄(또는 위아래 줄)로 표현하며, 본 프로젝트 권장 순서는 다음과 같습니다.

======
제목 1 (문서 제목)
======

제목 2
======

제목 3
------

제목 4
~~~~~~

경고

한글(전각 문자)은 폭이 2로 계산되므로, 밑줄 길이를 제목보다 충분히 길게 하세요. 밑줄이 짧으면 sphinx-build -W 에서 빌드가 실패합니다.

목록

* 순서 없는 항목
* 또 다른 항목

#. 번호 매김 항목
#. 자동으로 번호가 매겨짐

코드 블록

.. code-block:: console

   $ tox -e docs

교차 참조와 toctree

다른 문서를 가리킬 때 :doc: 를 사용합니다.

자세한 내용은 :doc:`../introduction/index` 를 참고하세요.

새 문서를 추가하면 상위 index.rst 의 toctree 에 반드시 등록합니다.

.. toctree::
   :maxdepth: 1

   new-page

admonition (참고/경고)

.. note::

   참고할 내용입니다.

.. warning::

   주의할 내용입니다.

로컬 환경 준비

문서 빌드에는 tox 사용을 권장합니다.

$ tox -e docs    # HTML 빌드 (경고를 오류로 처리)
$ tox -e pep8    # doc8 로 rST 스타일 검사

tox 없이 직접 빌드하려면 가상 환경을 사용합니다.

$ python -m venv .venv
$ . .venv/bin/activate
$ pip install -r doc/requirements.txt
$ sphinx-build -W -b html doc/source doc/build/html