상호 참조 추가 (Adding cross-references)
Sphinx의 강력한 기능 중 하나는 문서, 섹션, 그림, 코드 개체 등과 같은 문서의 특정 부분에 상호 참조 를 원활하게 추가하는 기능이다.
상호 참조를 추가하려면 의 도입 단락 바로 뒤에 이 문장을 선언한다 index.rst.
Check out the :doc:`usage` section for further information.
사용한 역할 은 프로젝트의 특정 문서를 자동으로 참조한다. 이 경우 이전에 생성한 것이다. doc usage.rst
또는 프로젝트의 임의 부분에 상호 참조를 추가할 수도 있다. 이를 위해 역할을 사용하고 대상 역할을 ref하는 명시적 레이블 을 추가해야 한다.
예를 들어, "설치" 하위 섹션을 참조하려면 다음과 같이 제목 바로 앞에 레이블을 추가하면 된다.
Usage
=====
.. _installation:
Installation
------------
...
그리고 추가한 문장을 index.rst 다음과 같이 만든다.
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
여기서 trick을 주목해야 한다. install 부분은 링크가 어떻게 생겼는지 지정하는 반면 (특정 단어가 되기를 원하므로 문장이 의미가 있음) <installation>부분은 상호 참조를 추가하려는 실제 레이블을 참조한다. 명시적 제목을 포함하지 않으면 를 사용 :ref:`installation`하여 섹션 제목이 사용된다 (이 경우 Installation). 여기서, :doc:과 :ref:의 role은 HTML 문서에서 하이퍼링크로 렌더링된다.
https://www.sphinx-doc.org/en/master/tutorial/narrative-documentation.html#adding-cross-references
Narrative documentation in Sphinx — Sphinx documentation
Structuring your documentation across multiple pages The file index.rst created by sphinx-quickstart is the root document, whose main function is to serve as a welcome page and to contain the root of the “table of contents tree” (or toctree). Sphinx al
www.sphinx-doc.org
'Python Library' 카테고리의 다른 글
| [Sphinx] Describing code in Sphinx (Other languages) (2) (0) | 2022.05.02 |
|---|---|
| [Sphinx] Describing code in Sphinx (Python) (1) (0) | 2022.05.02 |
| [Sphinx] Narrative documentation in Sphinx (1) (0) | 2022.05.02 |
| [Sphinx] More Sphinx customization (2) (0) | 2022.05.02 |
| [Sphinx] More Sphinx customization (1) (0) | 2022.05.02 |
