oinume journal

Scratchpad of what I learned

Sphinxで複数のman pageを生成する

前置き

つい最近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がおすすめです!

 

[tmkm-amazon]4274068641[/tmkm-amazon]