このタイトルでわかる人がどれだけいるんだろうか。epydoc が「一世を風靡」したことはないからなぁ。
pygribの作者の Jeff Whitaker がpyprojの作者であることまでは把握していて、なおかつ「少々プロジェクト管理が雑なひと」というとこまでが、ワタシの知っていた Jeff Whitaker だったが、メールアドレスから、NOAA (アメリカ海洋気象庁)の人だと知った。どーりでアカデミックなことばっかやってんだ。そして雑な理由もね。pyks「data assimilation for the 1-d Kuramoto-Sivashinsky equation」なんてことやってんの見てちょいと興味持っちゃって。(ちょっと調べたら、 時空カオスを示す偏微分方程式、だと。難しすぎてさっぱりわからん、が、気象の人ならこれをやるのも納得。)
で、その Jeff Whitaker が「ちょっかいを出していた」のが、pdoc。epydocは、たとえば pyxb が使っていたりしたこともあって、かなり古くから知ってたが、紹介する気にはなれないほど嫌いだった。読みにくいし。
「ひょっとして docstring と doctest、あまり浸透してない?」で、「Sphinx＝sphinx-apidocじゃない」と言ったが、この「primary goal」の考え方の違いと、その「違いに気付いていない」記事はあちこちで見つかるので、正直嫌になる。Sphinx の目指すものは「ドキュメント自動生成」ではなく、「利用者目線のちゃんとしたドキュメントの作製支援(翻訳の邪魔もしない)」にあって、「API ドキュメントを生成するのに Sphinx と epydoc があるらしい」と紹介されると、ちょいと迷惑だ。作成支援の一つ、としての、docstring からの自動抽出が位置づけられているんであって、自動抽出は目的じゃないす。手段だす。
「ドキュメントを作る」という全体像(*)ではなくて、「ドキュメント作成をサボりたいから自動生成したいし、翻訳なんか知ったこっちゃない」(*)向きに使えるもの(もしくはリバースエンジニアリング目的の自動ドキュメント)、ということなら、sphinx-apidoc はあんまし「最適」とは言えない。それはいつでも「翻訳の可能性」を捨てない(*)ので、ソース to ドキュメント、という直接変換は踏まえていないから。「ひょっとして docstring と doctest、あまり浸透してない?」でも書いた通り、(Cythonいらないなら)Doxygen の方が遥かに気軽に柔軟に色々出来る(し、美しい)。Doxygen の UMLLook なんかアタシは好きだ。
今ちょいと言ったように、特に少人数のプロジェクトの場合、プログラミングとドキュメント付けがどうしても不可分になって、コードとドキュメントを分離して考えるのが難しいことがあるのは確かであるし、「リバースエンジニアリング」には、自動ドキュメント生成は不可欠とも言える。であるから、決して Doxygen や epydoc 流儀が否定されるものではなく、無論非常に有用で、パワフルで…「使える」。単にゴールが違うだけのこと。そう、「APIリファレンスだけで十分」なケースだって、そりゃぁあるわけだ(*)。
てわけで、こんな Motivation：
で作られたという pdoc、どんだけっすかね?
インストールは pip で素直に出来た。pygments は入れといた方がいーぞ。入ってないと Syntax Hilighting してくんないらしい。
そしてそもそもワタシの「懸念」が的中しているドキュメント。これみて、動かし方わかる人、手あげろ。そゆこと。答えはこっち。API リファレンスてのはそういうことであろう。利用者は「API リファレンスだけが見たい」のとちゃう。
さっそく動かしてみる。—http はワタシのこれと同じノリである：
1 me@host: ~$ pdoc --http # SimpleHTTPServer的
2 pdoc server ready at http://localhost:8080
いきなりエンコーディングエラーが出た。あーぁ。対処はしました。察してね。ここには書かない。
ついでにスタイルが気に喰わない。epydocは「かっこ悪い上に読みにくい」だったので、pdoc はかっこいいというか「美しい」だけ十分良いが、フォントサイズが大きすぎて平気で文字欠けしてみたり wrap しまくりで、やたらに読みづらい。
pdoc/templates を直せばいいのね、と喜び勇んで修正するも、ちっとも反映されず。なんじゃこりゃ? と思って、うーん、キャッシュしてんのか? と疑い、ソースを眺めたら、そもそも「キャッシュ場所」をコマンドライン引数で制御出来(—http-dir)、このデフォルトが
1 default_http_dir = path.join(tempfile.gettempdir(), 'pdoc-%s' % version_suffix)
である、と。うーん、だるいなぁ、と、いったんサーバを止め、
1 me@host: ~$ rm -fv /tmp/pdoc*
2 removed `/tmp/pdoc-2.7/argparse.m.html'
3 removed `/tmp/pdoc-2.7/ConfigParser.m.html'
4 removed `/tmp/pdoc-2.7/msilib/index.html'
5 removed `/tmp/pdoc-2.7/msilib/schema.m.html'
6 removed `/tmp/pdoc-2.7/msilib/sequence.m.html'
7 removed `/tmp/pdoc-2.7/msilib/text.m.html'
8 removed directory: `/tmp/pdoc-2.7/msilib'
9 removed `/tmp/pdoc-2.7/_abcoll.m.html'
10 removed `/tmp/pdoc-2.7/_curses_panel.m.html'
11 removed `/tmp/pdoc-2.7/_hashlib.m.html'
12 removed directory: `/tmp/pdoc-2.7'
13 me@host: ~$
てわけで、こんなん出ました：
スタイルさえ制御出来れば、まぁまぁ実用になるかいね。あんまし Doxygen との差別化になるような「をぉ」もない気もするけれども。(インストール済み全モジュール、てのはまぁ Doxygen だと厳しいので、その意味では気軽で良いかね。)
なお Cython については、まさにその Jeff Whitaker のちょっかい、をみてちょ。Pull Request あげとる。今この PR、コンフリクトしちょるんで、でける人しかでけんでしょうが、でける人はやっちみれ。でけん人は、マージされるまで待てや。
ところで、ワタシが sphinx-apidoc に否定的に思われたらやなんで一応。そもそもワタシのように、「Sphinxじゃなきゃやだ!」という人なら、そりゃ sphinx-apidoc を使えや。ワタシが言いたいのは、「Sphinx = API ドキュメント自動生成ツールの一味」と見做されることの危険性の話。せっかく Sphinx のおかげで「色んなドキュメントが利用者目線に向かっている」のに、「API リファレンスだけ作っとけ」てな逆行したらたまらんのよ。
