前置き
つい最近tomahawkのドキュメントをGithub WikiからSphinxに移行したのでそのメモ。SphinxにはHTMLを生成する以外にもman pageを生成する機能があって
$ make man
を実行すると _build/man/ 配下に mycommand.1 みたいな感じでman pageが生成される。
でで、tomahawkの場合は tomahawk, tomahawk-rsync という2つの実行ファイルがあるので、この2つのman pageを生成したくて、tomahawk.rst, tomahawk-rsync.rst ファイルを作ってみたけど、デフォルトでは tomahawk.1 に全部入りのman pageができるだけで「独立したrstファイルから個別のman page生成するのってどうやるんだろう?」となっていた。
複数のman pageを生成する方法
結論としては、Sphinxのconf.pyに man_pages という設定があるので、これを下記のように man pageの数だけ用意してあげれば良かった。
authors = ('Kazuhiro Oinuma')
man_pages = [
('index', 'tomahawk-all', 'tomahawk manual', authors, 1),
('tomahawk', 'tomahawk', 'enables to execute a command to many hosts', authors, 1),
('tomahawk-rsync', 'tomahawk-rsync', 'enables to copy files to many hosts', authors, 1),
]
それぞれのタプルは順に
- source start file - manページの”ルート”となるドキュメントの名前です。このファイルから参照されたすべてのドキュメントはLaTeXファイルの中のTOCツリーにも含まれるようになります。もしも1つのファイルをマスターにしたmanページにしたい場合には、 master_doc で設定した値をここに指定して下さい。
- name - manページの名前です。これには、スペースや特別な文字を含まない、短い文字列を指定します。この項目は出力ファイル名と、manページの名前(NAMEセクション内)として使用されます。
- description - manページの説明です。これはNAMEセクション内で使用されます。
- authors - 著者名の文字列のリスト、もしくは単一の文字列です。manページのAUTHORSセクションを自動的に生成したくない場合には、空の文字列や空の配列を指定することもできます。
- section - manページのセクションです。出力ファイル名や、manページのヘッダー内で使われます。
ということらしい。このように複数のman pageを生成するやり方はSphinxのドキュメントにも書いてなかったので、Sphinx自体のドキュメントのソースを見てみたらビンゴだった。
なんでSphinxを使うのか
mkouheiさんにtomahawkのDebianパッケージを作ってもらっている時に「コマンドにはman pageが必要」といわれたので、どうせならHTMLもmanも生成できるSphinxに移行してみたというのが理由。最初はreStructuredTextのフォーマットを覚えるに苦労したけど、これさえ覚えれば色んなフォーマットに出力できるのでいい投資かなぁと思う。
あと、Read The Docsというサービスを使えば、Git/Mercurial/Bzr/SVNで管理しているファイルから自動的にSphinxでHTML生成して readthedocs.org から見れるようになるので非常に便利れす(ReadTheDocsについて詳しくはここ)。
というわけでソフトウェアのドキュメントにはSphinxがおすすめです!