sphinx-apidocのsetuptools統合

下記よりも良いプラクティスを投稿しました。この投稿のプラクティスも条件によっては通用するプラクティスだと思うので、とりさげずおきます。

はじめに

sphinx-apidocは強力なAPIドキュメンテーション作成自動化ツールです。setuptoolsにはsphinx統合ツールが存在しますが、sphinx-apidocを使うためには、一度CLIでsphinx-apidocを実行したあと、setuptoolsでsphinxをビルドする必要があるなど、自動化がいまいちです。このポストでは、1コマンドでsphinx-apidocとsphinxを両方実行する方法について記載します。

ちなみに自分はOSS開発に携わっているというわけではないので、下記が良いプラクティスかはわかりません。

方法

準備

Sphinxをインストールし、ドキュメントをディレクトリーを作成します。

$ pip install sphinx 
$ sphinx-quickstart

quickstartにしたがって適当に質問を埋めてゆきます。下記には今回の方法をとるのに回答が必要な質問だけ集めています。

Welcome to the Sphinx 1.6.1 quickstart utility.

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

Enter the root path for documentation.
> Root path for the documentation [.]: doc

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]: y

...

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y

すると、ディレクトリ以下に下記のような構成のdoc/ディレクトリが作成されます。

├── doc/
│   ├── build/
│   └── source/
│       ├── _build/
│       ├── conf.py
│       ├── index.rst
│       ├── _static/
│       └── _templates/
├── README.md
├── setup.cfg
├── setup.py
├── test/
├── my_project/

ビルド用のコード追加

setup.pyを下記のように書きます。sphinxのみを使う場合はsetup(cmdclass = {'build_sphinx': BuildDoc}, ...)とだけ書くのですが、今回はそのBuildDocを継承し、前処理としてapidocを追加したコマンドを新しく定義します。

setup.py

import os

from setuptools import setup
from setuptools.extension import Extension
import sphinx.apidoc
from sphinx.setup_command import BuildDoc

class BuildDocApiDoc(BuildDoc, object):
    # inherit from object to enable 'super'
    user_options = []
    description = 'sphinx'
    def run(self):
        # metadata contains information supplied in setup()
        metadata = self.distribution.metadata
        # package_dir may be None, in that case use the current directory.
        src_dir = (self.distribution.package_dir or {'': ''})['']
        src_dir = os.path.join(os.getcwd(),  src_dir)
        # Run sphinx by calling the main method, '--full' also adds a conf.py
        sphinx.apidoc.main(
            ['', '-f', '-H', metadata.name, '-A', metadata.author,
             '-V', metadata.version, '-R', metadata.version, '-T',
             '-o', os.path.join('doc', 'source', 'modules'), src_dir])
        super(BuildDocApiDoc, self).run()


name = 'my_project'
version = '0.1'
release = '0.1.0'

setup(
    name=name,
    author='koreyou',
    version=version,
    packages=['my_project', ],
    license='Creative Commons BY',
    cmdclass = {'build_sphinx': BuildDocApiDoc},
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release)}},
    setup_requires = ['sphinx'],
)

他にも、いくつかのファイルを書き換えます。

setup.cfg

[build_sphinx]
source-dir = doc/source
build-dir  = doc/build
all_files  = 1

doc/source/conf.py

-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../..'))

doc/source/index.rst

 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+      :glob:
+      :caption: Modules
+      :maxdepth: 4

+      modules/*

実行

python setup.up build_sphinx

いろいろと情報がながれたあと、正常に終了すればdoc/build/html/index.html以下にAPIドキュメンテーションが作成されるはずです。

また、バージョン管理ですが、doc/source/modulesは自動生成されるので、doc/source/conf.pyとdoc/source/index.rstのみをいれ、doc/buildとdoc/source/moduleは.gitignoreにいれています。

参考

• Stackoverflow, "Autogenerate documentation for Python project using setuptools"