Sphinx 導入

Sphinx 導入

Pythonのソースコードなどのドキュメントを作成するための静的なツールです。 reStructuredTextで記述してHTMLやPDFとしてドキュメントを出力します。

導入

pipを通してSphinxを導入します。docs/ディレクトリを作成し、そちらのディレクトリ以下に初期化をします。

$ pip3 install Sphinx
$ mkdir docs
$ sphinx-quickstart docs

コマンドを実行するにあたって、いくつかインタラクティブに質問されるので、例えば以下のように回答していきます。

> Separate source and build directories (y/n) [n]: y
> Project name: my_project
> Author name(s): Me
> Project release []: 0.0.1
> Project language [en]: en

先程の最初に質問にyで答えると、docs/以下にsource/ディレクトリが作成され、それ以下にconf.pyが作成されますので、こちらを編集していきます。nと答えた場合はdocs/以下にconf.pyが作成されます。

$ vim docs/source/conf.py

sys.path.insertを含む以下のコメントアウトされている箇所をコメントを外して、例のように編集します。../../src/my_projectはサービスが実装されたコードのパスです。

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

以下になっている箇所を修正後の例のように編集します。

extensions = [
]

• 修正後

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

# Include Python objects as they appear in source files
# Default: alphabetically ('alphabetical')
autodoc_member_order = 'bysource'
# Default flags used by autodoc directives
autodoc_default_flags = ['members', 'show-inheritance']

setup.pyから実行しない場合は、以下のようにドキュメントを作成します。

$ sphinx-apidoc -f  -o ./docs/source src
$ sphinx-build -b html ./docs/source ./docs/build

setup.pyから操作するときは、先程のsphinx-apidocとsphinx-buildコマンドは実行せず、setup.py(もしくはsetup.cfg)を編集していきます。setup.pyを編集する場合は、以下を追加します。

from setuptools.extension import Extension
import sphinx.ext.apidoc
from sphinx.setup_command import BuildDoc
 
class BuildDocApiDoc(BuildDoc, object):
    user_options = []
    description = 'sphinx'
    def run(self):
        src_dir = 'src/my_project/sample'
        src_dir = os.path.join(os.getcwd(),  src_dir)
        sphinx.ext.apidoc.main(
            ['-f', '-o', os.path.join('docs', 'source', 'modules'), src_dir])
        super(BuildDocApiDoc, self).run()
 
name = 'My-Project'
version = '0.0'
release = '0.0.1'

以下のように追加のインストールパッケージとしてSphinx、パッケージの除外対象としてdocsディレクトリを追加します。

• setup_requires

setup_requires=["pytest-runner", "Sphinx"],

• packages

packages=find_packages(where="src", exclude=("test","docs",)),

最後に以下を追加します。

cmdclass = {'build_sphinx': BuildDocApiDoc},
command_options={
    'build_sphinx': {
        'project': ('setup.py', name),
        'version': ('setup.py', version),
        'release': ('setup.py', release),
        'source_dir': ('setup.py', 'docs/source'),
        'build_dir': ('setup.py', 'docs/build')}},

setup.pyから実行するときは以下のコマンドを実行

$ python setup.py build_sphinx 

.gitignoreに以下を追加しておきます。

/docs/build/
/docs/source/modules/

docs/build/index.htmlをクリックしてブラウザで開くことで、生成されたドキュメントを確認できます。

• 参考

  • sphinxでpythonのクラスや関数のドキュメントを自動生成する

  • Sphinxによるドキュメント作成と国際化の事始め

Errors

checking consistency... /Users/hayshogo/workspace/ElastiCache-ORA-DG/docs/source/modules.rst: WARNING: document isn't included in any toctree

ファイルの先頭に:orphan:を追加することでエラーを解消。

• 参考

  • document isn't included in any toctreeという警告が出る