파이썬 flask 개발 문서 만드는데 5분. Sphinx.
문서 작성도 개발의 일환입니다.
개발자는 깔끔한 문서를 만들고 싶지만,
문서 작성에 많은 시간을 들이고 싶지는 않지요.
Sphinx가 바로 그 딜레마를 해결해 주는 도구입니다.
Sphinx로 파이썬 Flask 개발 문서 만들기 순서
- Sphinx와 sphinxcontrib-httpdomain를 설치합니다.
$ pip install sphinx
$ pip sphinxcontrib-httpdomainproject 폴더에 doc 폴더 생성합니다. - doc 폴더로 갑니다.
- sphinx-quickstart를 실행하여 기본 설정을 잡습니다.
$ sphinx-quickstart - conf.py에 다음을 추가합니다.
sys.path.append(os.path.abspath('..'))
# 확장
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.intersphinx',
'sphinxcontrib.autohttp.flask']
# 테마 (default|basic|sphinxdoc|scrolls|agogo|traditional|nature|haiku|pyramid)
html_theme = "nature"
기본으로 제공하는 테마 외에도 내려받거나 직접 만든 테마도 사용 가능합니다. - rst파일을 생성합니다.
API 예시
Users
--------------------------
.. autoflask:: application.api:create_app()
:undoc-static:
# api에 포함시키고 싶지 않은 blueprints.
:undoc-blueprints: - 문서를 생성합니다.
$ make html
참고 자료
http://sphinx-doc.org/tutorial.html
http://sphinx-doc.org/theming.html
http://pythonhosted.org/sphinxcontrib-httpdomain/
by 月風
