Subscribed unsubscribe Subscribe Subscribe

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]