[Python] 스핑크스(sphinx)를 이용한 파이썬 API 문서화 Develop Tip

예전 C, C++ 등을 포함하여 Python 에도 doxygen을 이용하고는 했습니다.
다양한 언어 및 클래스, 함수 등의 디펜던시 등을 도식화 해주고 나름 장점이 많았습니다.

그러나 최근에 다시 문서화에 대하여 알아보다가,
python.org 홈페이지에 있는 문서가 스핑크스(sphinx)라는 
문서화 도구로 만들어졌다는 것을 알았습니다.

결국 파이썬의 철학처럼 소스안에 문서화를 하여
자동으로 문서가 만들어진다는 생각이었습니다.

하지만 샘플을 찾았더니 참조할 한글 설명이 많지 않더군요.
그래서 정리해 보았습니다.

간단하게는 다음과 같이 하면 됩니다.

다음의 myPKG.tgz 파일 다운로드합니다.

1) 스핑크스 Doc 설치

$ sudo pip install Sphinx


2) 다음에 이 파일을 특정 폴더에 해제합니다.

$ mkdir ~/sphinx_doc
$ cd ~/sphinx_doc
$ tar xvfz myPKG.tgz


3) 파이썬 패스 추가

실제 스핑크스를 기동시키는데 해당 모듈이 접근 가능해야 합니다.

$ export PYTHONPATH=$PYTHONPATH:~/sphinx_doc


4) 모듈의 클래스 혹은 함수 등의 API 생성

$ cd ~/sphinx_doc
$ sphinx-apidoc -F -f -o apidoc myPKG


5) 실제 HTML 문서 생성

$ cd ~/sphinx_doc/apidoc
$ make html


주의: 위와 같이 하면 디폴트로 파이썬 모듈의 소스가 포함됩니다. 이를 포함 안 시키려면,

$ cd ~/sphinx_doc/apidoc
$ vi conf.py

extensions = [
    'sphinx.ext.autodoc',
#    'sphinx.ext.viewcode',
]

위와 같이 'sphinx.ext.viewcode' 부분을 코멘트로 막고 

$ make html

하면 됩니다.


다음은 간단한 작성 방법입니다.

스핑크스는 흡사 미디어위키의 글을 작성하는 것과 유사한
 reStructuredText 라는 텍스트를 이용하여 작성합니다.


1) 파이썬 모듈 시작 부분

#!/usr/bin/env python
#coding=utf8
"""
====================================
 :mod:`mod2` 모듈2 
====================================
.. moduleauthor:: 홍길동 <gdhong@foo.org>
.. note:: Future's NDA License

설명
=====

이 mod2 모듈은 스핑크스 문서화를 위한 테스트2 입니다

참고
====

참고:
 * http://sphinx-doc.org/
 * http://docutils.sourceforge.net/rst.html

관련 작업자
===========

본 모듈은 다음과 같은 사람들이 관여했습니다:
 * 개발2실 홍길동
 * 개발2실 둘리

작업일지
--------

다음과 같은 작업 사항이 있었습니다:
 * [2023/22/22] - 함수AAA 추가
 * [2023/22/02] - 본 모듈 작업 시작
"""

위에서 ==== 등과 같은 것은 섹션으로 자동 분류됩니다.


2) 글로벌 변수 부분

다음과 같이 글로벌 변수부분을 선언할 수 있습니다.

GLOBAL_VAR2 = 2234
''' 글로벌 변수 GLOBAL_VAR2 : 어디 어디 사용됨

.. versionchanged:: 2.2
           Removed deprecated argument: options
'''
GLOBAL_VAR2 = False
''' 글로벌 변수 GLOBAL_VAR2 : 어디 어디 사용됨 디폴트 False '''


3) 함수 선언 부분

다음과 같이 일반 함수에 관한 API 문서를 작성합니다.

#########################################################################################
def func_foo(a,b,c=None,d=0,e=[]):
    """ 모듈2에 있는 func_foo 함수

    이모듈은요 테스트 함수에 대한 것입니다.
    설명은 계속 이렇게 넣으시면 됩니다.

    :param str a: 실제로 str이 와야 합니다. 그 안에서 테스트

            :class:`basestring` 참조
    :param object b: 아무거나 (None 포함) 와도 됩니다. 하지만 빠지면 안됩니다.
            그 다음 줄에 설명이 계속 나와요. 참조 :func:`func_bar`

        .. note:: 주의할 점
        .. warning:: 워닝!!!
    :param c: 아무값이 올 수 있고 생략가능 합니다. (생략되면 None값)
    :param int d: 정수값이 올 수 있고 생략가능 합니다. (생략되면 0값)
    :param e: 리스트값이 올 수 있고 생략가능 합니다. (생략되면 []값)
    :type e: dict or list
    :return: int, str. int 리턴 코드는 다음과 같습니다::

            0 -- 성공!
            2 -- 실패2
            2 -- 재시도.

        리턴 문자열은 입력된 문자열을 담고 있습니다.
    :raises TypeError: 입력 형식이 잘못된 경우 raise
    :raises ReferenceError: 로직에서 참조 오류인 경우 raise

    다음과 같이 사용할 수 있습니다.

    >>> print func_foo('abc',2)
    (0, 'func_foo(a="abc",b=2,c=None,d=0,e=[])')
    """
    pass


4) 클래스 선언부분

다음과 같이 클래스 선언을 합니다.

#########################################################################################
class Bar(mod1.Foo):
    """테스트 myPKG.mod2.Bar 클래스
    """
    #====================================================================================
    def __init__(self, a, **kwargs):
        """ Bar 클래스 생성자

        :param a: 생성자 패러미터
        :param **kwargs: 키워드 패러미터 (생략가능)

        .. versionchanged:: 2.2
            패러미터 **kwargs 추가

        >>> f = Bar(223)
        """
        self.a = a
        for k,v in kwargs.items():
            setattr(self, k, v)
    #====================================================================================
    def method2(self, b, c):
        """ Bar method2 메소드

        :param str a: a 패러미터
        :param int b: b 패러미터

        :return: int 0

        >>> print Bar(223).method2('bb',33)
        0
        """
        return 0


그러면 아래와 같은 화면들이 나옵니다.


 모듈 상단에 넣었던 섹션이 나옵니다.

클래스 및 글로벌 변수 문서가 위와 같이 나옵니다.

위와 같이 함수 설명이 나오구요.

검색 창에서 함수 이름뿐만 아니라, 설명에 있는 내용까지 전문검색이 가능합니다.
(한글 검색도 잘 됩니다)


어느 분께는 도움이 되셨기를...

핑백

  • 한글이 잘 보이는지..? | parannamu 2015-05-21 05:30:49 #

    ... ython-guide/blob/master/docs/dev/virtualenvs.rst 해야할일 스핑크스(sphinx)를 이용한 문서작성 : http://mcchae.egloos.com/11080328 데코레이터에 대한 고찰 : http://mcchae.egloos.com/11030528 Pycharm을 이용한 원격디버깅 : http ... more

덧글

  • 오곡 2014/02/28 06:05 # 삭제 답글

    잘배우고 갑니다~
  • 지훈현서아빠 2014/02/28 08:41 #

    도움이 되셨다니 저의 보람입니다~~ ^^
  • 사랑을구걸하는거지 2014/04/09 12:09 # 삭제 답글

    좋은 정보 감사합니다...
  • 지훈현서아빠 2014/04/09 20:16 #

    도움이 되셨다니 저의 보람입니다~~ ^^
  • 초보 2014/06/12 16:43 # 삭제 답글

    안녕하세요 좋은 글 감사합니다.

    혹시 PyCharm과 스핑크스 연동방법도 알고 계신가요?
  • 지훈현서아빠 2014/06/13 17:09 #

    별도로 스핑크스와의 연동은 없이 그냥 소스 안에 넣어서 사용하고 있습니다...
  • 곰곰 2015/03/23 21:47 # 삭제 답글

    잘 보고 갑니다.
  • 지훈현서아빠 2015/03/23 21:52 #

    도움이 되셨다니 저의 보람입니다~~
  • 제임스 2017/03/01 15:13 # 답글

    파이선만 검색하면 무조건 문창님 불로그네요 ^^
    매일 파이선 사용한지 몇개월 된 것 같고요.
    열심히 따라가고 있습니다.
    늘 감사드리고요 문창님~
  • 지훈현서아빠 2017/03/03 10:36 #

    ㅎㅎ 그런가요?
    제가 바쁜거가 3월중순에 지나는데 그 후에 다시 한번 뵙고
    이런 저런 이야기를 나누시지요~ ^^
  • 제임스 2017/03/08 14:51 # 답글

    좋죠. 기대하고 있겠습니다. 문창님~
댓글 입력 영역

구글애드텍스트