oinume journal

Scratchpad of what I learned

Sphinxでソフトウェアのドキュメントを書いた時によく使う記法

最近Sphinxでよくドキュメントを書くのでメモ。やっぱりある程度巨大なソフトウェアのドキュメントを書く時はWikiじゃなくてSphinxの方が良い気がする。

 

リンク

他のファイルのセクションにリンクを貼るときには

 

 

  • そのセクションの前で .. _label: のようにラベル定義

 

 

  • :ref:`label`でリンクを張る

 

 

という感じ。ラベルの名前はドキュメント全体でユニークにする必要がある。

 

参考

 

ソースコードのinclude

literalincludeを使う。外部のソースファイルをincludeする時に使った。

 

.. literalinclude:: ../../src/main/java/net/lampetty/commons/MarkingStopwatch.java

:language: java

:linenos:

 

 

参考

 

テーブル

通常のテーブルの書き方は非常に面倒なので csv-table 使った。

 

 

.. csv-table::

:header: オプション, エイリアス, 必須, 意味

:widths: 30, 15, 8, 80

 

--url, -r, ◯, DBの接続先URL

--user, -u, ◯, DBの接続ユーザ

--password, -p, ☓, DBの接続パスワード

 

みたいな感じ。

 

参考

 

ハイフンx2を正しく出力する

Sphinxでは文中に --option みたいに書くと"ー"(全角のハイフン)に置換されてしまう。コマンドラインオプションを表す時に--をよく使うのでどうしようかと思ったら、``--option`` のようにインラインリテラル化すれば大丈夫であった。

 

参考

 

 

[tmkm-amazon]4774156167[/tmkm-amazon]

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]