ドキュメントを作成したくなってしまう魔法のツール、Sphinxのドキュメントを日本語訳しました。普通に使う分には問題ない、レベルまで完了しました。残る部分もぼちぼちやっていきますが、拡張機能の部分は最後まで手を付けないと思うので、自分で拡張したい方はがんばって英語(とソースコード)を読んでください。
- reStructeredText(reST)採用で、HTMLやPDFが作成できる
- reSTを拡張して様々な記述が簡単できるようになっている。コードハイライト、BNF、モジュール、クラス、関数などのソースコードのドキュメンテーションなど
- 1ファイル変換ではなくて、複数ソースの"プロジェクト"として管理できて、ドキュメント間リンクの面倒を見てくれる。
- 目次の生成
- 用語集とのクロスリファレンス
- モジュールインデックス、全体インデックスなど
- 変換時に用語インデックスをJSONで出力し、JavaScriptだけの全文検索エンジン内蔵。
使い勝手としては
- sphinx-quickstartコマンドを起動。質問に答えていく
- フォルダができるので、reStructuredText形式のファイルを追加、目次にファイル名を入れる
- 必要に応じてディレクティブ群を駆使してマークアップ
- makeコマンドを実行。
- ドキュメント完成！
という感じです。最近よくある、Webのフレームワークみたいな感じですよね。
Sphinxならではの部分では、特に用語集のところが秀逸。ロールというタグで意味を指定していくと、そのドキュメント内限定"はてな"みたいなことができます。ロールは拡張機能を作成することで、増やすことができます。世の中みんながSphinxを使うとセマンティックウェブの世界に近づきますよね。自分の閉じた世界の中での意味体系を自分でゼロから構築できます。Sphinxの先にWebの未来があるのを感じます。 通常のHTML生成では、人間が読みやすいドキュメントを作り、その裏でXML形式で意味体系を機械的に処理できるフォーマットで出力したり、これから流行る？マイクロフォーマットで出力したり、といったことが考えられます。Zopeのときもそうだったけど、時代を置き去りにしている感を感じさせてくれるツールです。「それPythonでもうできるよ」的な。Pythonやっていて良かった、と本気で思います。
それはそうと、ドキュメントを作成したくなる、ツールという触れ込みは伊達じゃないです。すでにブログで紹介した、Erlang Efficiency Guideの日本語訳でも使用しましたが、この程度の小さいドキュメントwでは、ディレクティブがほとんど使えず、「力をもてあましている」という感じがするんですよね。もともとはPythonのドキュメントを作成するのを目的に開発されただけあって、言語仕様、ライブラリリファレンス、C言語拡張、チュートリアルなどなど、１部だけ切り出してきても本を一冊書けちゃうよ、というドキュメント群の規模ぐらいないと「物足りないなぁ」なんて思ってしまうのかもしれません。仕事でも使って見ようかな。
毎度、面白いものを紹介してくれる、id:Voluntasには感謝です。
