파이썬(python) 라이브러리 - sphinx (docstirng 자동 문서화)

python 코드 내에 작성한 docstirng을 자동으로 문서화 해주는 아주 강력한 라이브러리다.

def 함수명():

   ''' 내용 ''' → 주석안에 특정 규칙에 맞게 작성해둔 docstring을 파싱한다.

 

예시

아래 예시는 Goolge Style 의 docstring 이다. (Napoleon 이라는 확장을 사용하여 파싱해야 함)
기본 docstring 형태는 알아서 찾아보도록.. 나는 개인적으로 Google Style이 가독성이 좋아서 선호한다.

def convert_worksheet_to_df(workbook, sheet_name=['Sheet'], include_index=False, include_column=False):
    """ Excel 파일에서 원하는 Sheet를 지정해 list(Dataframe) 으로 반환

    Args:
        file_path (str): 저장할 대상 Excel Workbook
        sheet_name (list): Excel Workbook의 Sheet명
        include_index (bool, optional): index 포함여부
        include_column (bool, optional): column(header) 포함여부

    Returns:
        dict (sheet_name : pandas.DataFrame)
        
    Raises:
        ValueError: File path를 입력하지 않은 경우
        FileNotFoundError: File path의 경로에 파일 찾을 수 없는 경우

    """

 

결과물

sphinx install

---

현재 위치아래에 생성되므로 원하는 위치에 docs 폴더를 만들고 안에 들어가서 수행한다.

pip install sphinx 수행

우리는 Google Style docstring을 사용할 것이므로 nappoleon 도 추가로 설치한다.

pip install sphinxcontrib-napoleon

 

Napoleon 공식 문서 :

Napoleon - Marching toward legible docstrings — napoleon 0.7 documentation

 

기본 디렉토리 구조

---

하나의 폴더 안에 docs와 my_pacakge(스크립트가 들어간 디렉토리)를 두고 사용하면 된다.

아래는 sphinx-quickstart docs 를 수행한 뒤의 디렉토리 모습이다.

 

폴더 분리하지 않은 경우

---

 

Separate source and build directories (y/n) [n]: n

docs
├── build
├── make.bat
├── Makefile
├── conf.py
├── index.rst
├── _static                            
└── _templates

my_pacakage
├── __init_.py
└── my_module.py

 

 

폴더 분리한 경우

---

Separate source and build directories (y/n) [n]: y

source 폴더가 생성 된다. 관리 편의성을 위하여 특별한 사유 없으면 분리해서 사용하도록 하자

 

docs
├── build
├── make.bat
├── Makefile
└── source
   ├── conf.py
   ├── index.rst
   ├── _static                            
   └── _templates
  
my_pacakage
├── __init_.py
└── my_module.py

 

build/

An empty directory (for now) that will hold the rendered documentation.

make.bat and Makefile

Convenience scripts to simplify some common Sphinx operations, such as rendering the content.

source/conf.py

A Python script holding the configuration of the Sphinx project. It contains the project name and release you specified to sphinx-quickstart, as well as some extra configuration keys.

source/index.rst

The root document of the project, which serves as welcome page and contains the root of the “table of contents tree” (or toctree).

 

Quick Start 시작

---

스크립트들이 있는 모듈 디렉토리의 상위 디렉토리에서 docs폴더 생성 후
sphinx-quickstart docs 를 수행하면 docs아래에 sphinx에 관련된 폴더를 생성해준다.

 

Case 1

Separate source and build directories (y/n) [n]: n

C:\Users\pyexcel\docs>sphinx-quickstart
Welcome to the Sphinx 3.2.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: n

The project name will occur in several places in the built documentation.
> Project name: pyexcel
> Author name(s): hoon
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ko

Creating file C:\Users\pyexcel\docs\conf.py.
Creating file C:\Users\pyexcel\docs\index.rst.
Creating file C:\Users\pyexcel\docs\Makefile.
Creating file C:\Users\pyexcel\docs\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file C:\Users\pyexcel\docs\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

 

Case 2

Separate source and build directories (y/n) [n]: y

C:\Users\pyexcel\docs>sphinx-quickstart
Welcome to the Sphinx 3.2.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: pyexcel
> Author name(s): hoon
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ko

Creating file C:\Users\pyexcel\docs\source\conf.py.
Creating file C:\Users\pyexcel\docs\source\index.rst.
Creating file C:\Users\pyexcel\docs\Makefile.
Creating file C:\Users\pyexcel\docs\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file C:\Users\pyexcel\docs\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

 

Autodoc 사용하기

---

Sphinx는 파이썬 소스코드로부터 자동으로 문서를 생성해 주는 'Autodoc'을 제공한다.

 

conf.py 설정

---

-autodoc을 사용하기 위해서는 source/conf.py의 'extensions' 부분에 반드시 아래와 같이 autodoc이 추가되어 있어야 한다.

... (생략) ...
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinx.ext.autodoc','sphinx.ext.todo','sphinx.ext.napoleon'
]
todo_include_todos = True
... (생략) ...

• sphinx.ext.napoleon : Google Style docstring 사용시 파싱을 해주는 extensions이다.
• sphinx.ext.todo : Google Style docstring 사용시 Todo: 라고 적은 부분을 변환해줌. todo_include_todos=True값도 세트로 같이 설정해야 한다.
• sphinx.ext.autodoc : 모듈을 자동으로 문서화해주는 extensions이다.

 

그리고, 파이썬 코드가 있는 path도 sys.path에 들어있어야 하므로 conf.py에 추가한다. path는 반드시 절대경로로 들어있어야 하므로 상대경로 일 경우 os.path.abspath를 이용해 절대경로로 바꿔서 설정한다.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # docs/source/conf.py 인 경우
sys.path.insert(0, os.path.abspath('..'))    # docs/conf.py 인 경우
# 만약 경로 못찾는다 나오면 아래와 같이 풀경로 넣어야함
sys.path.insert(0, os.path.abspath('C:\\Users\\pyexcel\\my_package'))

 

index.rst 설정

---

source/index.rst는 document의 첫페이지가 된다. 아래와 같이 toctree를 이용해서 목차를 만들 수 있다. 목차에 입력한 my_package는 index.rst와 같은 경로에 있는 'my_package.rst' 를 자동으로 찾아서 목차로 만들어 준다.

#index.rst 예제
My documentation
================

Content:

.. toctree::
    :maxdepth: 2

    my_package

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

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

 

 

sphinx-apidoc 사용

---

모듈이 생성/삭제 되었을 경우 재수행 필요
스크립트 내용만 수정했을때는 굳이 재수행하지 않아도 된다.

__init__.py 파일은 포함되지 않는다.

sphinx-apidoc는 autodoc 확장을 사용하여 자동 API 문서 도구 스타일로 전체 패키지를 문서화하여 .rst 파일을 생성하는 CLI 유틸리티입니다. 명령의 형식은 다음과 같습니다.

 

형식
sphinx-apidoc [ 옵션 ] -o < OUTPUT_PATH > < MODULE_PATH > [ EXCLUDE_PATTERN ...]

• [옵션] -F : 이미 존재하는 .rst 파일들을 강제 overwrite (덮어쓰기) 하겠다는 옵션
• -o OUTPUT_PATH : 생성된 소스가 있는 디렉토리입니다. 
• MODULE_PATH : 문서화할 Python 패키지의 경로
• EXCLUDE_PATTERN : 생성에서 제외될 fnmatch 스타일 파일 및/또는 디렉토리 패턴입니다.
  --serperate : 각 모듈에 대한 문서를 자체 페이지에 넣습니다.
  이 옵션을 주면 모듈 내 파일 마다 .rst 파일이 생성된다.
  옵션 주지 않으면 모듈명.rst 하나에 전체 파일 정보가 들어간다.

단점
결과 문서에 색인, 목차가 없음. 개체가 많으면 sphinx.ext.autosummary 사용하도록

 

예시 

sphinx-apidoc -F -o ./docs/source ./my_package

my_pacakge라는 이름의 모듈경로의 패키지를 자동 문서화하여 .rst 파일을 생성하고 docs 위치에 위치시킨다. 이미 같은 이름의 .rst 존재한다면 강제 덮어쓰기 한다.

※ docs와 module의 상위 폴더에서 수행해야 함.

C:\Users\pyexcel>sphinx-apidoc -F -o docs my_package/
Creating file ./docs/source\my_package.rst.
File C:\Users\pyexcel\docs\source\conf.py already exists, skipping.
File C:\Users\pyexcel\docs\source\index.rst already exists, skipping.
Creating file C:\Users\pyexcel\docs\source\Makefile.
Creating file C:\Users\pyexcel\docs\source\make.bat.

 

 

 

sphinx-apidoc -F -o ./docs/source ./my_package --separate

→ docs 아래에 Makefile. make.bat. 가 이미 있지만 docs/source/ 아래에 새로 생성된다. 왜이런지 확인 필요하다 ㅠ

C:\Users\hoon\pyexcel>sphinx-apidoc -F -o docs my_package/ --separate
Creating file docs\my_package.rst.
Creating file docs\my_package.pandastool.rst.
Creating file docs\my_package.pyexceltool.rst.
Creating file docs\my_package.pywinexceltool.rst.
Creating file C:\Users\pyexcel\docs\conf.py.
Creating file C:\Users\pyexcel\docs\index.rst.
File C:\Users\pyexcel\docs\Makefile already exists, skipping.
File C:\Users\pyexcel\docs\make.bat already exists, skipping.

결과
index.rst 의 doctree에 my_package가 추가되어 index.html 접속하면 my_package가 보인다.

 

Make html 수행

---

rst문서를 참조하여 HTML파일들이 생성된다.
make.bat 을 까보면 내부적으로 sphinx-build를 사용하므로 둘 중 아무거나로 수행하면 된다.

 

make.bat 파일이 위치한 docs 폴더에서 명령어 make html 수행

C:\Users\pyexcel>cd docs

C:\Users\pyexcel\docs>make html
Running Sphinx v3.2.1
loading translations [ko]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

 

결과 파일

docs\source_build\html\ 아래에 html 파일이 생성된다.
index.html 이 최상단 웹페이지다. 열어본다.

 

 

sphinx-build

---

rst문서를 참조하여 HTML파일들이 생성된다. make html 명령어로 대신 수행 가능

 

공식 문서

sphinx-build — Sphinx documentation

 

 

형식

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

• sourcedir : conf.py 파일이 있는 상위 폴더를 넣어야 함

-b 옵션으로 는 다양한 형식의 문서를 생성 할 수 있습니다. (기본값은 HTML)
명령줄에서 빌더 이름을 지정하여 형식을 선택합니다. 빌더는 문서 처리와 관련된 다른 작업도 수행할 수 있습니다. 사용 가능한 빌더 목록은 를 참조하십시오 .

• -b singlehtml : 하나의 html 파일로 빌드

예시

sphinx-build -b singlehtml ./docs/source ./docs/build

 

 

sphinx.ext.autosummary 확장

---

이 기능은 아직 테스트해보지 못하여 추후 사용해보면 포스팅 예정

 

 

문서 테마 변경

source/conf.py의 'html_theme'에 원하는 테마를 입력한 후 make html을 실행하면 자동으로 css를 받아오고 html을 생성해준다.

테마 구경 :

Sphinx Themes Gallery

여러가지 사용해봐야 알겠지만… 지금까지는 adc 테마가 그나마 가독성이 괜찮아보여서 사용중

 

adc 테마 사용시

1. pip install sphinx-adc-theme

2. conf.py 파일에 아래 내용 추가

import sphinx_adc_theme
html_theme = 'sphinx_adc_theme'
html_theme_path = [sphinx_adc_theme.get_html_theme_path()]