ちょい前からずっと紹介したくて、なぜだか見つからなかったやつ。
あ、sphinx-users.jp の中だったか。
こんな発言に注目、かもな:
私は、autodocはドキュメントの自動生成と手書きとの間のほぼ完璧なバランスを取れていると思っているから、とても大事な機能だね。自動生成されたものは大抵醜い獣となり、すでに良く知っているソフトウェアでなければ理解できない程度になる。チュートリアルはソースコードの中にいれたくないから、置き場所がない。手書きのドキュメントは書くのが退屈で山のように書く必要があるけれど、大体の場合これがあるとドキュメントが読みやすくて分かりやすくなるから、個別の解説文はソースコードの中に入れられるようになる。だからPythonはこの方法を取っているんだ。
…
私が完全な自動化をあんまり好きではないため、自動ドキュメント生成のsphinx-apidocはそんなに頭が良くない。でも、他の人は興味があると思う。
あとこれも:
これみてて、ワタシの記憶違いを知った。Python 公式サイトが Sphinx ベースになったの、ずっと 2.7 からだと思ってたが、2.6 からだったみたい。