liminfoSphinx Reference
Sphinx 문서화 도구 레퍼런스
Sphinx Reference 소개
Sphinx 레퍼런스는 Python 문서 생성을 위한 검색 가능한 빠른 참조입니다. 목차 계층 구조를 구축하는 toctree, 참고 및 경고 상자를 위한 note/warning, 구문 강조와 줄 번호 옵션이 포함된 code-block, 미디어 삽입을 위한 image, 소스 파일에서 직접 코드를 가져오는 literalinclude 등 필수 디렉티브를 다룹니다. 각 항목에는 자주 사용되는 옵션이 포함된 전체 디렉티브 구문이 포함되어 있습니다.
이 레퍼런스는 Sphinx 기능을 디렉티브, 역할, 설정, 확장, 테마, autodoc의 6가지 카테고리로 구성합니다. 역할 섹션에서는 :ref:, :doc:, :func:, :class:, :meth:, :term:을 사용한 교차 참조로 상호 연결된 문서를 구축하는 방법을 다룹니다. 설정 섹션에서는 프로젝트 메타데이터, 확장 로딩, html_theme 선택, 국제화를 위한 언어 설정, 빌드 범위 제어를 위한 exclude_patterns 등 conf.py 설정을 제공합니다.
확장 및 테마 섹션은 기본 문서화를 넘어 Sphinx를 확장하는 방법을 안내합니다. Python 독스트링에서 API 문서를 자동 생성하는 autodoc, Google/NumPy 독스트링을 지원하는 napoleon, 프로젝트 간 교차 참조를 위한 intersphinx, 소스 코드 링크를 위한 viewcode, 문서 작업 추적을 위한 todo 확장을 다룹니다. 테마 섹션에서는 alabaster, Read the Docs, Furo, Book 테마를 설정 예제와 함께 비교합니다.
주요 기능
- toctree, note, warning, linenos가 포함된 code-block, image, literalinclude를 위한 디렉티브 구문
- 틸드 축약형을 포함한 :ref:, :doc:, :func:, :class:, :meth:, :term: 교차 참조 역할
- 프로젝트 메타데이터, 확장 목록, html_theme, language, exclude_patterns를 위한 conf.py 설정
- autodoc, napoleon(Google/NumPy 독스트링), intersphinx, viewcode, todo 확장 설정
- alabaster, Read the Docs, Furo, Book 테마의 설정 예제가 포함된 테마 비교
- members, show-inheritance, special-members 옵션을 포함한 autodoc 디렉티브(autoclass, autofunction, automodule)
- Python 패키지에서 API 문서 스캐폴딩을 생성하는 sphinx-apidoc CLI 도구 사용법
- 모듈 전반에 걸친 일관된 문서 생성을 위한 autodoc_default_options 설정
자주 묻는 질문
toctree 디렉티브란 무엇이며 maxdepth는 어떻게 작동하나요?
toctree 디렉티브는 여러 .rst 파일을 계층적 내비게이션 구조로 연결하는 목차 트리를 생성합니다. :maxdepth: 옵션은 트리에 표시되는 제목 수준의 깊이를 제어합니다. 예를 들어 :maxdepth: 2는 문서 제목과 첫 번째 수준의 섹션을 표시합니다. :caption: 옵션은 트리 위에 제목을 추가합니다. 문서는 파일 확장자 없이, 현재 파일 기준 상대 경로로 한 줄에 하나씩 나열됩니다.
:ref:와 :doc:를 사용한 교차 참조는 어떻게 사용하나요?
:ref:는 ".. _my-label:" 같은 타겟을 사용하여 문서 내 라벨이 지정된 위치로 링크합니다. :doc:는 파일 경로로 전체 문서에 링크합니다. 특정 섹션으로 링크할 때는 파일 이동에 강건한 :ref:가 선호됩니다. :func:`~module.function` 같은 역할의 틸드(~) 접두사는 짧은 이름만 표시합니다. 둘 다 HTML 출력에서 적절한 하이퍼링크를 생성합니다.
autodoc과 sphinx-apidoc의 차이점은 무엇인가요?
autodoc은 .. automodule::과 .. autoclass:: 같은 디렉티브를 사용하여 Python 독스트링에서 문서를 자동 생성하는 확장입니다. sphinx-apidoc은 전체 Python 패키지에 대해 해당 autodoc 디렉티브를 포함하는 .rst 스텁 파일을 생성하는 CLI 도구입니다. 일반적으로 sphinx-apidoc을 한 번 실행하여 파일 구조를 만든 후 생성된 .rst 파일을 커스터마이즈합니다. autodoc은 매 빌드마다 실행되어 현재 독스트링을 추출합니다.
Google 스타일 독스트링을 위한 napoleon은 어떻게 설정하나요?
conf.py의 extensions 목록에 "sphinx.ext.napoleon"을 추가합니다. Google 스타일에는 napoleon_google_docstring = True, NumPy 스타일에는 napoleon_numpy_docstring = True를 설정합니다. napoleon은 이러한 사람이 읽기 쉬운 형식을 autodoc이 처리할 수 있는 표준 reStructuredText로 변환합니다. __init__ 문서화를 위한 napoleon_include_init_with_doc과 파라미터 포맷을 위한 napoleon_use_param이 주요 옵션입니다.
intersphinx는 무엇이며 어떻게 설정하나요?
intersphinx는 다른 Sphinx 프로젝트에서 문서화된 객체에 대한 교차 참조를 가능하게 합니다. extensions에 "sphinx.ext.intersphinx"를 추가하고 프로젝트 이름과 URL로 intersphinx_mapping을 정의합니다. 예: intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}. 그런 다음 :func:`json.dumps`를 사용하여 Python 표준 라이브러리 문서에 직접 링크할 수 있습니다. None 파라미터는 objects.inv 파일을 자동으로 다운로드하도록 지시합니다.
Furo, Read the Docs, alabaster 테마 중 어떤 것을 선택해야 하나요?
alabaster는 Sphinx의 기본 테마로 미니멀하고 깔끔하지만 기능이 제한적입니다. Read the Docs(sphinx_rtd_theme)는 가장 인기 있으며, 깊은 중첩을 지원하는 사이드바 내비게이션과 익숙한 레이아웃을 제공합니다. Furo는 다크 모드 토글, 깔끔한 타이포그래피, 더 나은 모바일 반응성을 갖춘 모던 테마입니다. Book 테마(sphinx-book-theme)는 Jupyter 노트북 실행 버튼이 포함된 튜토리얼과 교육 콘텐츠에 이상적입니다.
외부 파일의 소스 코드를 어떻게 포함하나요?
literalinclude 디렉티브를 사용합니다: ".. literalinclude:: path/to/file.py". 옵션으로 구문 강조를 위한 :language:, 줄 범위를 지정하는 :lines:(예: 1-10), 줄 번호를 위한 :linenos:, 특정 줄을 강조하는 :emphasize-lines:, 마커 사이의 코드를 추출하는 :start-after: / :end-before:가 있습니다. 이를 통해 수동 복사 없이 문서를 실제 소스 코드와 동기화할 수 있습니다.
다국어 문서를 위한 Sphinx 설정은 어떻게 하나요?
conf.py에서 language = "ko"(또는 대상 언어)를 설정합니다. locale_dirs = ["locale/"]를 구성하고 gettext_compact = False를 설정합니다. "sphinx-build -b gettext"를 실행하여 번역 가능한 문자열을 추출한 후, sphinx-intl을 사용하여 번역용 .po 파일을 생성합니다. 각 언어는 별도의 출력으로 빌드됩니다. 여러 언어 버전을 동시에 필요로 하는 프로젝트에서는 다른 언어 설정으로 별도 빌드를 구성할 수 있습니다.