Sphinx 導入
hayashierPythonのソースコードなどのドキュメントを作成するための静的なツールです。 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をクリックしてブラウザで開くことで、生成されたドキュメントを確認できます。
Errors
checking consistency… /Users/hayshogo/workspace/ElastiCache-ORA-DG/docs/source/modules.rst: WARNING: document isn’t included in any toctree
ファイルの先頭に:orphan:を追加することでエラーを解消。
