はじめに

現在着手している機械学習の自作ライブラリを作る際のテストやドキュメントの管理にSphinxを使用してみようと思い立ち、いろいろいじってみたのですが思っていた構造にするのに手間取ったのでメモして共有します。以下の記事はこちらの記事を参考にしてアップデートされた部分や詰まったところを重点的に書いていきます。

環境

python 3.7.3
Sphinx 2.1.2

GitHubリポジトリ(こちら)をクローンしていただき、pip install -r requirements.txtでSphinxのインストールができます。ディレクトリ構成も同じになるので検証していただける方は是非。

$ git clone https://github.com/CastaChick/Example_of_Sphinx.git

上記をコピペでクローンできます。

ディレクトリ構成

Sphinxを始める前の構成

.
├── README.md
├── article.md
├── docs
├── packages
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── __init__.cpython-37.pyc
│   │   └── example.cpython-37.pyc
│   └── example.py
└── requirements.txt

Sphinxを用いてこのdocsディレクトリ内にドキュメントを自動的に追加できるようにしていきます。

ソースコードをpackagesに全部まとめ、docsでドキュメントを管理していく構図にしたいと考え、これを実現していきます。

example.pyにはコメントをつけた２つの関数が入っています。
詳しくはソースコードを参照してください。

ドキュメントを作る

いよいよドキュメントを作っていきたいと思います。

1. 雛形を作る

docsに移動してShinxを開始します。

$ sphinx-quickstart

ソースディレクトリとビルドディレクトリは分けておきます。

この結果docs以下にこのようなディレクトリとファイル達が作られます。

.
├── Makefile
├── build
├── make.bat
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

2. 設定を記述する

今回、自動的にドキュメントを生成したいのでconf.pyのextensionsに設定を追記して以下のようにします。

conf.py

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

また、conf.pyのはじめのコメントアウトされている部分を書き換えてpackagesへのpathを通します。サブパッケージを作ったときにはここに追記してpathを通しましょう。

conf.py


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

3. ドキュメントに追加する

動作確認ができたのでドキュメントに追加する作業を行なっていきます。

目次を追加

source/index.rstを以下のように書き換えて目次にexampleが追記されるようにします。後々他のモジュールを追加するときにもexampleの下に追加することで目次に順次追加されていきます。

source/index.rst


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

    example

新しいモジュールについてのページを追加

以下のようなsource/example.rstを作成します。:member:とすることでexample.py内で定義された全ての関数が反映されます。

source/example.rst


Example
=======

.. automodule :: example
    :members:

ドキュメントを更新

いよいよこれらのファイルを元にドキュメントを更新していきます。

docsディレクトリで以下のコマンドを実行するとbuild内にhtmlディレクトリが生成され、ドキュメントがhtmlファイル化されます。

$ make html

4. 確認してみよう！

現在のディレクトリ構成は以下のようになっていると思います。($ tree —-filelimit 10を実行)

.
├── README.md
├── article.md
├── docs
│   ├── Makefile
│   ├── build
│   │   ├── doctrees
│   │   │   ├── environment.pickle
│   │   │   ├── example.doctree
│   │   │   └── index.doctree
│   │   └── html
│   │       ├── _modules
│   │       │   ├── example.html
│   │       │   └── index.html
│   │       ├── _sources
│   │       │   ├── example.rst.txt
│   │       │   └── index.rst.txt
│   │       ├── _static [16 entries exceeds filelimit, not opening dir]
│   │       ├── example.html
│   │       ├── genindex.html
│   │       ├── index.html
│   │       ├── objects.inv
│   │       ├── py-modindex.html
│   │       ├── search.html
│   │       └── searchindex.js
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── example.rst
│       └── index.rst
├── packages
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── __init__.cpython-37.pyc
│   │   └── example.cpython-37.pyc
│   └── example.py
└── requirements.txt

build/html/index.htmlをブラウザで開くとドキュメントがきちんと生成されていることがわかると思います。関数の説明や引数、使用例もコメント通りに翻訳されて書き出されていますね！example.pyを書き換えたときには$ make htmlを実行するだけでドキュメントも更新されます。

終わりに

今回はまずはじめにコメントのついたソースコードを元にドキュメント化していきましたが、実際のテスト駆動開発では『テストコメント→テスト→実装→テスト→APIコメント→ドキュメント化』のような流れで進んでいきます。詳しくはこちらに親切に書いてあります。これから本格的に機械学習ライブラリを実装していくので完成したらぜひ見てください！

なお今回の記事は昨夜初めてSphinxに触れた超初心者が主に公式ドキュメントを調べて自分なりに構築したものなのでもっとこうした方が良いという改善点があれば是非教えてください！

Sphinxを使って自作パッケージのドキュメントを簡単に更新しよう！！