[Sphinx] Narrative documentation in Sphinx (1)

여러 페이지에 걸쳐 문서 구조화 (Structuring your documentation across multiple pages)

 

index.rst에 의해 생성된 파일 sphinx-quickstart은 루트 문서이며, 주요 기능은 시작 페이지 역할을 하고 "목차 트리" (또는 toctree)의 루트를 포함하는 것이다. Sphinx를 사용하면 다른 파일에서 프로젝트를 조합할 수 있으므로 프로젝트가 커질 때 유용하다.

 

예를 들어, 다음 내용 으로 새 파일 docs/source/usage.rst (index.rst 옆에)을 만든다.

 

Usage
=====

Installation
------------

To use Lumache, first install it using pip:

.. code-block:: console

   (.venv) $ pip install lumache

 

이 새 파일에는 두 개의 섹션 헤더, 일반 단락 텍스트 및 code-block 적절한 구문 강조 표시 (이 경우 일반 console텍스트)와 함께 콘텐츠 블록을 소스 코드로 렌더링하는 지시문이 포함되어 있다.

 

문서의 구조는 연속된 표제 스타일에 의해 결정됩니다. 즉, "사용" 섹션 ---에 대해 "설치" 섹션을 사용함으로써 "설치"를 "사용"의 하위 섹션 ===으로 선언 했다.

 

프로세스를 완료하려면 다음과 같이 방금 생성한 문서를 포함하는 끝에 toctree 지시문을 추가한다.

 

Contents
--------

.. toctree::

   usage

 

이 단계는 해당 문서를 toctree 루트에 삽입 하므로 이제 프로젝트 구조에 속한다. 지금까지는 다음과 같다.

 

index
└── usage

 

실행 중인 HTML 문서를 빌드하면 하이퍼링크 목록으로 렌더링되는 것을 볼 수 있으며 이를 통해 방금 만든 새 페이지로 이동할 수 있다.

 

https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html

Narrative documentation in Sphinx — Sphinx documentation