1. 개요

sphinx는 파이썬 코드를 분석하여 txt, html 같은 문서를 만들어주는 프로그램이다. 프로젝트 폴더 구조와 사용 절차는 다음과 같다.

/project/src/
    package/
        module.py
            MyClass

/project/sphinx/
    conf.py
    index.rst
    package.rst
    package.module.rst

/project/doc/html/
    index.html
    package.html
    package.module.html
  1. 파이썬 소스에 주석을 단다.
  2. sphinx-quickstart 로 sphinx 프로젝트를 생성한다.
  3. sphinx-apidoc 로 파이썬 코드가 담긴 src폴더의 구조를 분석하여 rst 파일들을 만든다.
  4. sphinx-build 혹은 make로 src폴더와 rst파일들을 통해 html, txt 같은 문서들을 만들어낸다.

2. 파이썬 소스 파일 세팅

다음과 같은 형태로 소스 파일에 주석을 단다.

'''
My Module 설명
'''

class MyClass(object):
    '''테스트 클래스

    :param int a: a값
    :param int b: b값
    '''
    def __init__(self, a, b):
        self.a = a
        self.b = b

    def plus(self):
        '''미리 입력받은 a와 b값을 더한 결과를 반환합니다.

        :return: int a + b 에 대한 결과
        
        예제:
            >>> MyClass(2,1).plus()
            3
        '''
        return self.a + self.b

3. sphinx 설치하기

다음 명령으로 sphinx를 설치한다.

$ pip install sphinx

4. sphinx 프로젝트 만들기

sphinx 프로젝트 폴더(/project/sphinx)로 이동하고 다음 명령을 실행한다.

$ cd /project/sphinx
$ sphinx-quickstart

> Selected root path: .
> Separate source and build directories (y/n) [n]:
> Name prefix for templates and static dir [_]:
> Project name: MyProject
> Author name(s): TaewooLee
> Project release: 0.1
> Project language [en]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: **y**
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: **y**
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: **y**
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

그 결과, 다음과 같은 폴더와 파일들이 생성된다.

_build/
_static/
_templates/
conf.py
index.rst
make.bat
Makefile

5. sphinx 프로젝트 설정하기

sphinx 는 빌드시 conf.py 설정 파일을 사용한다.

우선 탐색할 모듈들을 찾을 수 있게 Path를 수정한다. conf.py 을 열고 상단 부분의 주석을 해제한 뒤, 경로를 수정한다.

import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

이제 sphinx에서 사용 할 모듈들을 설정한다. sphinx-quickstart 세팅시 몇 부분에서 y를 선택하지 않았다면 다음 항목이 만들어지지 않는다.

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
]

6. sphinx-apidoc

sphinx-apidoc은 파이썬 코드들을 분석한 뒤 문서를 만들 때 사용하는 rst 파일들을 생성한다.

$ sphinx-apidoc -F -o /project/sphinx /project/src --separate

7. index.rst

사용자가 가장 처음에 볼 페이지인 index.rst 파일을 수정한다. 여기에서 패키지 항목을 삽입해줘야 사용자가 항목을 자연스럽게 찾아 들어갈 수 있다.

.. MyProject documentation master file, created by
   sphinx-quickstart on Wed Mar 11 09:50:05 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to MyProject's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   myPackage

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

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

8. sphinx-build

sphinx-build는 파이썬 코드와 이전에 생성된 rst를 참고하여 txt, html 등을 생성해낸다.

$ cd /project/sphinx
$ make html
=> /project/sphinx/_build/index.html

$ sphinx-build -M html /project/sphinx /project/doc [options]
=> /project/doc/html/index.html

테마 바꾸기

Sphinx Themes 를 통해 테마를 찾고 설치한다.

$ pip install sphinx_rtd_theme

conf.py를 편집하여 테마를 적용한다.

html_theme = 'sphinx_rtd_theme'

참고자료