[python] Sphinx로 문서화하기

1. 설치

pip install -U sphinx

Installing Sphinx — Sphinx documentation

2. 시작하기

sphinx-quickstart

• 해당 코드를 입력하면 나오는 내용 (프로젝트 옵션 기재)

Welcome to the Sphinx 6.1.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: 

The project name will occur in several places in the built documentation.
> Project name: **<입력>**
> Author name(s): **<입력>**
> Project release []: **<입력 : 1.0 ~ >**

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
<https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language>.
> Project language [en]: **<입력 : 영어 기본값으로 엔터 치면 넘어감>**

Creating file <경로>/conf.py.
Creating file <경로>/index.rst.
Creating file <경로>/Makefile.
Creating file <경로>/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file <경로>/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

3. 초기 설정

• 만들고자 하는 프로젝트 폴더 내부에 __init__.py 파일을 생성
• 작성

'''
_module
* ~ 관련 모듈

:copyright: **<작성>**
:licence: **<작성>**
'''

__version__ = **<작성 : '1.0'>**

• docs/conf.py 파일에 내용 추가

import os
import shlex
import sys

sys.path.insert(0, os.path.abspath('..'))
from module import __version__ as VERSION

version = VERSION #추가
release = VERSION #수정

extensions = [
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx.ext.ifconfig',
    'sphinx.ext.napoleon',
    'sphinx.ext.imgmath',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.autodoc'
]

...

html_theme = 'sphinx_rtd_theme' #설치 필요 - pipenv install sphinx_rtd_theme 

• index.rst 파일 내용 추가 및 수정

**<프로젝트 명칭~>**
================================================

.. toctree::
   :maxdepth: 1
   :caption: Tutorial 

• Tutorial.rst 파일 생성 및 수정

Tutorial
=====================================================

.. automodule:: module.test
    :members:

4. 초기 실행

• docs/ 폴더로 들어가 make html 입력
• docs/_build/html/indel.html 열면 index 화면 확인 가능