[python] sphinx 빠르게 시작하기

처음으로 sphinx를 사용해볼때 빠르게 따라해볼 수 있는 방법을 소개한다.

 

1. 먼저 문서화하고자 하는 프로젝트를 준비한다.

 

GitHub - jaehaaheaj/sphinx-test

설명을 위해 매우 간단한 구조의 프로젝트를 만들어서 main 브랜치에 넣어두었다.

sphinx_test

├ obja.py

├ objb.py

└ things

  ├ thinga.py

  └ thingb.py

 

2. sphinx를 인스톨한다. venv 환경 activate하고 설치하자.

$ pip install sphinx

굳이 venv에다가 인스톨한건 추후 sphinx가 해당 프로젝트를 읽을때 편하게 하기 위함이다.

 

이 공식 문서에서는 위와 같이 인스톨하는 것을 설명하고 있다.

Installing Sphinx — Sphinx documentation

흥미로운 건 같은 공식문서인데 여기서는 venv환경에서 인스톨하는 걸 가정하고 설명한다.

Getting started — Sphinx documentation

 

3. 여기부턴 위의 getting started 문서를 따라한다. 먼저 sphinx가 제대로 설치되었는지 아래의 명령어로 확인한다.

$ sphinx-build --version
sphinx-build 5.3.0

4. 퀵스타트로 레이아웃을 만든다.

내 경우 입력해야 하는 내용이 있을때 아래의 순서로 입력했다.

- y

- sphinx-test

- jaehaaheaj

- 0.0.0

- 그냥 enter 누름.

$ sphinx-quickstart docs
Sphinx 5.3.0 빠른 시작 유틸리티에 오신 것을 환영합니다.

다음 설정에 대한 값을 입력하십시오 (대괄호로 묶여 있는 기본값이 존재하고
이 값을 사용하려면 바로 Enter를 누릅니다).

선택한 루트 경로: docs

Sphinx 출력을 위한 빌드 디렉토리를 배치하는 두 가지 옵션이 있습니다.
루트 경로 내에서 "_build" 디렉토리를 사용하거나, 루트 경로 내에서
"source"와 "build" 디렉토리로 분리합니다.
> 원본과 빌드 디렉토리 분리 (y/n) [n]: y

프로젝트 이름은 빌드 된 문서의 여러 위치에 표시됩니다.
> 프로젝트 이름: sphinx-test
> 작성자 이름: jaehaaheaj
> 프로젝트 릴리스 []: 0.0.0

문서를 영어 이외의 언어로 작성하려는 경우, 여기에서 해당 언어 코드로 언어를
선택할 수 있습니다. 그러면 Sphinx가 생성한 텍스트를 해당 언어로 번역합니다.

지원되는 코드 목록은
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
를 참조하십시오.
> 프로젝트 언어 [en]: 

C:\code\sphinx-test\docs\source\conf.py 파일을 만드는 중입니다.
C:\code\sphinx-test\docs\source\index.rst 파일을 만드는 중입니다.
C:\code\sphinx-test\docs\Makefile 파일을 만드는 중입니다.
C:\code\sphinx-test\docs\make.bat 파일을 만드는 중입니다.

완료됨: 초기 디렉토리 구조가 생성되었습니다.

이제 마스터 파일 C:\code\sphinx-test\docs\source\index.rst을(를) 채우고 다른 원본 문서 파일을 만들어야 합니다. Makefile을 사용하여 다음과 같이 문서를 빌드하십시오:
   make builder
여기서 "builder"는 지원되는 빌더 중 하나(예: html, latex, linkcheck)입니다.

 

5. apidoc을 자동으로 생성한다. 위의 튜토리얼 링크에 나오는 내용은 아니다.

$ sphinx-apidoc -o docs/source sphinx_test/
docs/source\sphinx_test.rst 파일을 만드는 중입니다.
docs/source\sphinx_test.things.rst 파일을 만드는 중입니다.
docs/source\modules.rst 파일을 만드는 중입니다.

-o 뒤에 오는 내용은 순서대로 rst파일들을 저장할 위치, 그리고 rst파일을 만들 타겟들이 위치한 폴더로 생각하면 된다.

 

6. 앞 과정에서 생성한 modules.rst의 내용을 원래 있던 docs/source/index.rst에 넣어놓자.

아래의 코드블록에서 ..toctree:: 아래에 modules라는 줄을 추가한 것을 확인하자.

.. sphinx-test documentation master file, created by
   sphinx-quickstart on Sun Oct 23 17:53:47 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to sphinx-test's documentation!
=======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

7. docs/source/conf.py 파일을 수정한다.

아래의 코드블록에서 extensions변수 안에 'sphinx.ext.autodoc'을 추가한 것을 확인하자.

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'sphinx-test'
copyright = '2022, jaehaaheaj'
author = 'jaehaaheaj'
release = '0.0.0'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc'
]

templates_path = ['_templates']
exclude_patterns = []



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

8. sphinx가 해당 프로젝트의 모듈들을 잘 찾게 하기 위해서 프로젝트 자체를 인스톨하자.

$ pip install .

9. 다시 튜토리얼 페이지로 돌아가서, 해당 프로젝트를 sphinx로 build해주자.

$ sphinx-build -b html docs/source/ docs/build/html
Sphinx 버전 5.3.0 실행 중
출력 디렉토리 만드는 중... 완료
빌드 중 [mo]: 오래된 0 개의 po 파일 대상
빌드 중 [html]: 오래된 4 개의 원본 파일 대상
환경을 갱신하는 중: [새로운 설정] 4 개 추가됨, 0 개 변경됨, 0 개 제거됨
원본을 읽는 중… [ 25%] index
원본을 읽는 중… [ 50%] modules
원본을 읽는 중… [ 75%] sphinx_test
원본을 읽는 중… [100%] sphinx_test.things

오래된 파일을 찾는 중… 찾은 것이 없음
pickle로 환경을 저장하는 중... 완료
일관성 확인 중... 완료
문서 준비 중... 완료
출력을 쓰는 중… [ 25%] index
출력을 쓰는 중… [ 50%] modules
출력을 쓰는 중… [ 75%] sphinx_test
출력을 쓰는 중… [100%] sphinx_test.things

색인 생성 중... genindex py-modindex 완료
추가 페이지 작성 중... search 완료
정적 파일을 복사하는 중... 완료
추가 파일을 복사하는 중... 완료
English (code: en)에서 검색 인덱스 덤프 중... 완료
객체 인벤토리 덤프 중... 완료
빌드 성공.

HTML 페이지는 docs\build\html에 있습니다.

10. 완성! docs/build/html안에 있는 index.html을 열어보자. sphinx-apidoc으로 rst파일들을 생성해서 불필요한 정보들이 많이 들어간 문서가 나오긴 했지만, 이 정도면 sphinx를 다루는 걸 시작하는 데에는 무리가 없을 것이라 생각한다. 앞으로는 rst파일들을 좀 더 다듬으면서 봐줄만한 문서로 수정하면 된다.