Overview

プログラムがある程度の規模になってくると, 個人~数人規模でもドキュメントをつくるのがほぼ必須になってくると思います.

でもPythonのドキュメント生成ツールってあんまりいい感じのがないんですよね.

ほぼデファクトスタンダードになっているsphinxなんですけど, ほんとにみんなあんな苦行に耐えているのでしょうか？

最近のPythonではType HintsやVariable Annotationといった要素が追加され, mypyなどの静的型チェックによってプログラムのデバッグが格段に楽になりました.

なのに一生ドキュメント生成は楽にならない...

CythonですらType Hints, Variable Annotationをサポートしたというのにsphinxはといえばsphinx-quickstartがquickじゃなくなるばかりです.

誰か偉い人が作るのを待っているのだけどなかなか出てこないし, 仕方ないので自分でつくることにしました.

Usage

$ python py2markdown.py <SOURCE_DIRECTORY> <DESTINATION_DIRECTORY>

ツールの出来的にいって配布できるような状態じゃないので, この記事に影響されて卍最強エンジニア卍の方が開発してくれるのを待ちます

プルリクもらえたらリファクタリングがんばります.

Demo

試しにpy2markdown.py自体を本ツールでmarkdownにコンバートしてみました.

markdown -> htmlの変換にはVuepressを使っています.

Vuepressは基本gitbookみたいな感じなんですが, 見た目がかっちょいいのとvue.jsでコンポーネントがかけるのでいい感じです.

Issue

実はPythonの構文解析をしてるわけじゃなく, ゴリゴリ文字列処理をしています.

だから当然関数閉包みたいな変態記法には対応してません

副作用がめちゃくちゃなメソッドばっかりなので, できれば関数型っぽく書いて副作用を薄めたいんですけど, パフォーマンスにどの程度影響するか謎なのでその結果によってはCythonize, もしくはRustあたりでバシッと高速にキメたいですね.

研究で開発してる自作システムのソースが見やすくなればいいかな〜ってゆるいコンセプトで2~3時間でつくったものなのですが, 意外にもいい感じになったのでそのうちちゃんとした実装にしてみたいと思います.

お わ り