파이썬 문서화 방법과 도구

파이썬(Python) 문서화를 위한 방법과 도구를 알아 본다.

먼저 문서화 방법이다.

다양성 보다는 간결성을 추구하는 파이썬의 철학처럼, 규칙에 따른 주석 만으로 문서화 할 수 있다.

PEP 257 ( Docstoring Convension : 문서화 규칙) 을 바탕으로 주석을 다는 좋은 습관 만으로 충분하다.

기능 상자(모듈, 함수, 클래스, 메소드)의 첫번째 문장 주석은 __doc__ 라는 특별한 속성이 된다.

이 속성을 통해서 기능별로 구조화된 문서를 자동 생성할 수 있다.

다음은 문서화 도구이다.

자동 문서화 도구로 자주 언급 되는 Pydoc과 Sphinx를 비교한다.

• Pydoc
• 정말 단순한 방법으로 문서화를 제공한다.
• pydoc -b <module> 만으로 깔끔한 웹 문서를 볼 수 있다.
• 개발 중에 바로바로 문서화 해서 보기에 최적이다.
• 옵션이 빈약해서 문서 배포 용도로는 부족하다.
• Sphinx
• 상대적으로 복잡한 옵션과 방법으로 문서화를 제공한다.
• PyPI와 같은 대부분의 문서화 페이지에서 사용된다.
• 상세한 기능을 제공하며, 개발 후 문서화 배포에 최적이다.
• 다양한 테마의 HTML 디자인을 제공한다.

Pydoc은 워낙 단순해서 직관적으로 사용하고, Sphinx를 통해서 문서화 하는 과정을 간략히 소개한다.

1. 문서화 폴더(Directory) 생성

sphinx-apidoc -H <project name> -A <Author> -V <version> -R <release> -F -f -o <output path> <module path>

* <output path>에 문서화 관련 파일들이 생성된다.

2. 문서화 폴더에 생성된 conf.py (환경 설정 파일 : default )을 적절하게 수정한다.

 - 보통은 sys.path.insert에 <module path>를 등록한다.

 - 소스(source) 보기를 제외 할때는 extensions에 sphinx.ext.viewcode를 제거한다. 

 - 필자가 좋아하는 테마는 sphinx_rtd_theme 이다.

3. HTML로 생성(Build) 명령이다.

make clean; make html

* conf.py 파일을 참조 해서 수행된다.