sphinxとは？

ドキュメントを作るのがめんどくさい時に利用できるツールでして。

くわしくはこっちを見てください。

この記事の目的

このsphinxってやつは結構賢くて、有るパッケージ以下を認識させると、それ以下のpythonのパッケージを読み取ってくれて、 ファイルに記述されているコメントからドキュメント生成してくれます。

今回はそのコマンドを利用する際の注意点を幾つか挙げられれば。

コマンドの利用方法

インストール

1

pip install sphinx

利用方法

1
2
3

#sphinx-apidoc -f -o 出力先ディレクトリ調査対象ディレクトリ
#例) app内を調査し、docsに出力する
sphinx-apidoc -f -o docs/ app/

注意点

1. config.pyを書き換える
2. rst記法を学ぶ
3. __init__.pyが大事
4. ライブラリから関数をインポートしない
5. コメント内に章立てを入れない

以上の理由を軽く解説します。

1. config.pyを書き換える

プロジェクトのルートはインポートするようにしましょう。

ドキュメント生成の際に普通にモジュールをインポートしたりするので、インポートするパスを追加しておかないとドキュメントがきちんと生成されません。

1
2
3

import sys
import os
sys.path.append('/path/to/project/root')

2. rst記法

意外と面倒で、マークダウンほどのシンプルではありません。

はやわかり reStructuredText

なんだかんだ上記のページで学ぶのが一番しっかりしていて早いと思われます。

3. __init__.py大事

ディレクトリでネストしている際は__init__.pyを設置しましょう。

当たり前ですが、置かないとpythonが関連しているディレクトリとして認識されません。

4. ライブラリから関数をインポートしない

自分がハマったのですが、

1
2

# aというモジュール内でhogeモジュールのHogeクラス functioと言う関数を想定
from hoge.Hoge import function

上記のようにインポートするとは、インポートした関数(function)を、ドキュメント生成したい(a)モジュール内の関数だと認識し、 aというモジュールのドキュメント内に、functionのドキュメントも生成されます。

(誰得の機能なのだろうか?)

たとえばSQLAlchemyを利用している際に、ralationship関数を読み込んでいるとsphinx-apidocはrelatiohship関数のドキュメントも生成しようとします。

ただし、対象関数のコメントでエラーを吐いて正しくドキュメント生成されません。

1
2
3
4

#relationshipの関数までドキュメント生成される例
from sqlalchemy import relationship

relationship()

回避方法は以下のとおり

1
2
3
4

#ドキュメント生成されない例
import sqlalchemy as sa

sa.relationship()

5. コメント内に章立てを入れない

ソースコードのコメントで章立てをしないというのは、おそらく既に、モジュール名、クラス名、関数名で章立てができているので不要だからだと思います。

(はっきりと検証していないので不確かですが、)コメント内で章立てをするとエラーが出てまたしてもドキュメント生成されません。