• 사용한 코드의 매뉴얼을 만드는 방식 중에 Sphinx 모듈을 사용하는 방법이 있어 소개한다.

  • Sphinx

  Overview - Sphinx documentation

  • 설치 방법

    pip install -U Sphinx # 파이썬 파일 문서화 패키지
    pip install sphinxcontrib-napoleon # Sphinx 추가 기능 패키지
    

• Sphinx를 통해 코드를 한번에 문서화 하기 위해서는 특정 형식에 맞게 주석을 작성하여야 한다.

코드 주석 형식

• Python의 docstring (주석 형식)은 다양한 종류가 있다.

  • Epytext, reST, Google, Numpydoc
  • 참고 링크

  What are the most common Python docstring formats?

• 이 중에서 Google 형식을 사용하는 방법을 소개한다.

• 위에서 설치했던 sphinxcontrib-napoleon 은 Sphinx 패키지를 쓸 때 Google 형식을 해석할 수 있게 해주는 추가 기능 패키지 이다.

• 코드 상에서 맞춰야 형식은 다음과 같으며, 이와 같은 형식은 Google 형식이라고 한다.

  """
  This is an example of Google style.
  
  Args:
      param1: This is the first param.
      param2: This is a second param.
  
  Returns:
      This is a description of what is returned.
  
  Raises:
      KeyError: Raises an exception.
  """
  

🔑 Tip!

• VS code를 사용할 경우, Extension 중에 '**Python Docstring Generator'**를 사용하는 것을 권장한다.

  • Python Docstring Generator는 자동으로 위의 형식을 세팅해준다.

    

문서화 방법

코드가 있는 폴더를 기준으로 실행한다.

• 현재 디렉토리

my_project <-- 현재 경로
├ __init__.py
└ module.py

Step 1. 문서 빌드를 위한 파일 생성

• ~/my_project 에서 다음을 실행한다.

(가상환경) ~/my_project$ sphinx-quickstart docs

• 그럼 다음과 같은 화면이 뜨며, 필요 세팅을 설정할 수 있다.
  • 빨간색 음영 부분이 세팅 시 직접 설정해야 할 값이다. 그냥 Enter 키를 누르면 Default값으로 설정된다.

  • 원본과 빌드 디렉토리 분리 (y/n) [n]:

  프로젝트 이름: my_project 작성자 이름: dio 프로젝트 릴리스 []: 0.1 프로젝트 언어 [en]: ko

Sphinx 4.3.1 빠른 시작 유틸리티에 오신 것을 환영합니다.

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

선택한 루트 경로: docs

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

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

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

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

/home/ahn/vfr/my_project/docs/conf.py 파일을 만드는 중입니다.
/home/ahn/vfr/my_project/docs/index.rst 파일을 만드는 중입니다.
/home/ahn/vfr/my_project/docs/Makefile 파일을 만드는 중입니다.
/home/ahn/vfr/my_project/docs/make.bat 파일을 만드는 중입니다.

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

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