Python 패키지 개발일지 10: 스핑크스 레퍼런스 페이지 만들기

스핑크스(Sphinx)를 통해 만든 패키지의 레퍼런스 페이지를 만듭니다.

제가 제작하는 패키지 설명서는 튜토리얼과 레퍼런스 페이지를 분리하여 작업합니다. 튜토리얼 페이지는 패키지를 처음 접하는 사람들을 위해 작성하고, 레퍼런스 페이지는 패키지의 구조를 따라 문서를 구성하여 어느정도 패키지에 익숙한 사람들이 보는 용도로 작성합니다.

레퍼런스 페이지를 작성하는데 큰 수고를 들이지 않으려면 소스코드에 문서화문자열(docstring)을 잘 남겨두는것이 중요합니다.

관련글

• Python 패키지 개발일지 05: 주석을 이용한 문서화
• Python 패키지 개발일지 06: 스핑크스를 사용한 패키지 문서화
• Python 패키지 개발일지 07: 스핑크스 개인화
• Python 패키지 개발일지 08: 스핑크스 & 깃허브 페이지 (중급)

페이지 구조 만들기

패키지가 커짐에 따라 많은 설명이 필요하게 되어버리면 적당한 구조를 미리 만들어두지 않았을 때 고생하게 됩니다. 관리하는 여러가지 방법이 있겠습니다만, 저는 디렉토리로 관리하려고 합니다.

sphinx_source/
    ├─ index.rst      # 첫 페이지
    └─ reference/
        ├─ index.rst  # 레퍼런스 첫 페이지
        ├─ c_Gui.rst  # GUI 클래스
        │   ...
        └─ m_win32    # win32 모듈

이런 방식으로 파일 구조를 생성합니다.

index에 페이지 구조 입력하기

sphinx_source/index.rst

...
.. toctree::
  :maxdepth: 2

  reference/index
...

sphinx_source/reference/index.rst

...
.. toctree::
  :hidden:

   c_Gui
   ...
   m_win32
..

.. toctree::는 해당 페이지에 소속되어 있는 문서를 알리는 문법입니다. 설정과 페이지 위치를 들여쓰기로 인식합니다. 속성 :maxdepth: {숫자}는 어느정도의 깊이까지 표시할지 정합니다. 속성 :hidden: 하위페이지 목록을 실제 문서에 표시하지 말라는 의미입니다. 숨김을 선택한 경우 최대 깊이는 의미없는 속성이 됩니다.

문서화 문자열 활용

문서화 문자열을 가져올 때 스핑크스의 autodoc을 이용하게 됩니다. 예전 버전에서는 확장에 추가해야 작동했지만 최신 버전은 자동으로 지원하니 확장 추가 관련 부분은 다루지 않겠습니다. autodoc을 이용하는 방법에 대한 상세한 설명은 sphinx.ext.autodoc을 참고하시고, 여기서는 기초적인 패턴만 다루도록 하겠습니다.

변수나 함수

하위 모듈에 속하지 않은 변수나 함수 등은 한곳에 모아서 나열합니다.

sphinx_source/reference/index.rst

.. automodule:: autowinpy
  :members: __version__,  __dpi_scale_factor__

.. autofunction:: autowinpy.window_list
.. autofunction:: autowinpy.find_window

automodule은 모듈이나 패키지의 __init__.py 문서의 최상단 문서화 문자열을 가져옵니다. members 속성은 해당하는 모듈이나 패키지의 __init__.py에 속한 변수나 함수 등을 가져옵니다. members 속성에 특정 키워드를 주면 해당하는 함수, 변수만 나열합니다.

모듈

sphinx_source/reference/m_win32.rst

.. automodule:: autowinpy.win32
  :members:

automodule은 자동으로 모듈의 문서화 문자열을 불러옵니다. :members: 옵션은 추가로 모듈 파일에 속한 요소들과 문서화 문자열을 가져옵니다. 저는 이름 공간에 트릭을 사용했기 때문에 이 옵션으로는 함수를 불러올 수가 없어서 표시할 함수를 다음과 같은 방식으로 지정해야 했습니다.

sphinx_source/reference/m_win32.rst

.. automodule:: autowinpy.win32

  .. autofunction:: handle_list
  .. autofunction:: child_handle_list
  .. autofunction:: window_text
  .. autofunction:: window_rect
  .. autofunction:: window_array

autofunction을 들여쓰기 하면 자동으로 automodule의 하위 문서임을 표시하게 됩니다. 이것은 일일히 .. autofunction:: autowinpy.win32.handle_list처럼 쓸 필요가 없도록 해줍니다.

클래스

sphinx_source/reference/c_Gui.rst

============
Gui 클래스
============

.. autoclass:: autowinpy.Gui
  :members:
  :member-order: groupwise

member-order를 지정해 주지 않은 경우에는 기본값으로 알파벳 순 정렬입니다. groupwise 옵션은 멤버가 프로퍼티인지 메소드인지 같은 종류에 따른 분류를 우선하기 때문에 보기 편합니다. 클래스가 커지는 경우 섹션을 나눠야 할 필요가 있기 때문에 다음과 같은 방법을 사용합니다.

sphinx_source/reference/c_Gui.rst

============
Gui 클래스
============

.. autoclass:: autowinpy.Gui

객체
====
.. autoproperty:: autowinpy.Gui.hwnd
.. autoproperty:: autowinpy.Gui.name
.. autoproperty:: autowinpy.Gui.rect

함수
====
.. automethod:: autowinpy.Gui.childs
.. automethod:: autowinpy.Gui.image_array

이렇게 각각 분리해서 표시했습니다. 들여쓰기를 통한 이름 공간 생략은 여전히 효과가 있지만, 클래스에서 이 방법을 사용할 경우 어느 클래스에 속한 요소인지도 생략되어 읽는 사람이 헷갈릴 수 있습니다.