[Sphinx] 코드에서 자동 문서 생성 (2)

포괄적인 API 참조 생성 (Generating comprehensive API references)

 

sphinx.ext.autodoc를 사용하면 코드와 문서의 동기화를 훨씬 쉽게 유지할 수 있지만 auto* 문서화하려는 모든 개체에 대한 지시문을 작성해야 한다. Sphinx는 또 다른 수준의 자동화인 자동 요약 확장을 제공한다.

 

지시문은 autosummary필요한 모든 autodoc지시문을 포함하는 문서를 생성한다. 이를 사용하려면 먼저 자동 요약 확장을 활성화한다.

 

extensions = [
   'sphinx.ext.duration',
   'sphinx.ext.doctest',
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary',
]

 

api.rst다음 으로 다음 내용으로 새 파일을 만든다.

 

API
===

.. autosummary::
   :toctree: generated

   lumache

 

루트 toctree에 새 문서를 포함해야 한다.

 

Contents
--------

.. toctree::

   usage
   api

 

마지막으로 실행 중인 HTML 문서를 빌드하면 두 개의 새 페이지가 포함된다.

 

api.htmldocs/source/api.rst, 지시문에 포함된 개체가 있는 테이블에 해당 하고 포함한다 autosummary (이 경우 하나만). generated/lumache.html, 새로 생성된 reST 파일 generated/lumache.rst에 해당하고 모듈 멤버 요약을 포함한다 (이 경우 하나의 함수와 하나의 예외).

 

요약 페이지의 각 링크는 해당 autodoc지시문을 원래 사용했던 위치 (이 경우 usage.rst문서에서)로 이동한다.

 

https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html#generating-comprehensive-api-references

Automatic documentation generation from code — Sphinx documentation