そんなことができるツールを作りました。
https://github.com/tkamenoko/inari
動機
PEP287 でdocstringsのreStructured Textによる書き方が標準化されており、多くのPythonプロジェクトではそれに倣ってドキュメントが書かれている。しかし、PypiのReadmeにMarkdownファイルを使えるようになっているし、またMkDocsのような優れたMarkdownツールが現れ様々なプロジェクトで用いられている。だったらdocstringsもMarkdownで書いちゃえばいいじゃん！というのが主なモチベーション。
Sphinxの設定が複雑すぎるというのも動機の一つ。小規模なプロジェクトなら最小限の機能で十分だし、設定ファイルも込み入ったものは使いたくはない。最小限の設定で使えるものを目指した。
使い方
インストール
pipでインストールできる。依存ライブラリなしの単一コマンドとしても使えるけど、MkDocsと一緒に使うことを推奨。
pip install inari[mkdocs]
CLIとして使う
対象モジュールをインポートできることが前提。
inari <module-name> <out-dir> [-n <out-name>]
これで対象モジュールからdocstringsを取得してMarkdownファイルとして出力される。-n を指定することでモジュール名を使う代わりにdocs/<out-name> にファイルを出力できる。
.
├── docs
│ └── module-name
│ └── submodules
│ └── ...
│ └── index.md
└── module-name
├── __init__.py
└── submodules
└── ...
docs/module-name/index.md にはmodule-name/__init__.py のdocstringsに加えてサブモジュールへのリンクが自動生成される。
MkDocsプラグインとして使う
CLIでモジュールや出力先を指定する代わりにmkdocs.ymlを編集することでプラグインとして利用できる。
docs_dir: "docs" # `out-dir` に設定される
plugins:
- search # MkDocs default plugin
- inari:
module: <module-name> # required
out-name: api # optional. Default: <module-name>
あとはmkdocs build かmkdocs serve でドキュメントが生成される。
モジュール内参照
docstringsで`module.submodule.ClassName` のように記述すると、[`ClassName `](../submodule#Classname) のような相対リンクへと自動変換される。
まとめ
sphinx-apidocのようなツールをMkDocsに持ち込む、といったツールはこれが唯一というわけでは無いけれど、設定の簡便さを突き詰めたものは無かったと思う。ソースコードの表示のような追加したい機能もあるし、何よりテストが無いのはよろしくないので、今後もアップデートはしていく予定。MkDocsを使っている方はぜひ試してみてください。
ソースはhttps://github.com/tkamenoko/inari にあるので、改善案などがあればissue/PRを送って頂けると助かります。