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]