Sphinxでお手軽ドキュメント生成

キーバインドがおかしいとよく言われるemacs派のbokkoです。

今回はneoagentのドキュメンテーションに使用しているSphinxについて紹介します。

ドキュメンテーションツール Sphinx

Sphinxは様々な形式のドキュメントを生成できるツールで、reStructuredTextからHTMLやmanにはじまり、LaTeXやPDF、はてはEPUBといった形式に変換することができます。 特にHTMLドキュメントはデザインを設定一つでさまざまなテーマに切り替えることができるのでとても便利です。

Sphinxのインストール・セットアップ

SphinxをインストールするにはDebianやUbuntuであれば以下のコマンドを実行します。

1 2 3 4

$ aptitude install python-pip $ pip install Sphinx # あるいは $ aptitude install python-sphinx

あとは以下のコマンドを実行すればセットアップ完了です。

1	sphinx-quickstart

sphinx-quickstartを実行すると対話形式のプロンプトが出力されていろいろな入力を求められますが、必須項目は以下の3つだけです。

• Project name -> プロジェクト名
• Author name -> 作者名
• Project version -> プロジェクトのバージョン番号

セットアップが完了するとMakefileや設定ファイル(conf.py)、雛形ファイル(index.rst)ができるので、makeを実行してみましょう。以下はその出力です。

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

$ make Please use `make <target>' where <target> is one of html to make standalone HTML files dirhtml to make HTML files named index.html in directories singlehtml to make a single large HTML file pickle to make pickle files json to make JSON files htmlhelp to make HTML files and a HTML help project qthelp to make HTML files and a qthelp project devhelp to make HTML files and a Devhelp project epub to make an epub latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter latexpdf to make LaTeX files and run them through pdflatex text to make text files man to make manual pages texinfo to make Texinfo files info to make Texinfo files and run them through makeinfo gettext to make PO message catalogs changes to make an overview of all changed/added/deprecated items linkcheck to check all external links for integrity doctest to run all doctests embedded in the documentation (if enabled) $

このようにSphinxを使うといろいろな形式のドキュメントをコマンド一つで簡単に生成することができます。

1 2	$ make html # HTML形式のドキュメントを生成 $ make man # man形式のドキュメントを生成

実際に生成されるドキュメントの見栄えやレイアウト等はSphinxが全部面倒を見てくれるので あとは雛形ファイルのindex.rstを編集したり、新しいファイルや内容を追加していくことだけに集中できます。 これは特に手っ取り早く(CSSやJavaScriptも書かないといけない)HTML形式のドキュメントを生成したい場合に便利です。

neoagentとSphinx

neoagentではHTML形式のドキュメントと各コマンドのmanをSphinxで生成しています。

生成元の各reStructuredTextファイルや設定はこちらに、 実際に生成したHTMLドキュメントはこちらにありますので、Sphinxをこれから使おうと思っている方は参考にしてみてください。