Sphinx で Ruby の API ドキュメントを書く

Ruby

Ruby のライブラリ用に API ドキュメントを書く際に、簡単な数式（ギリシア文字、上付き、バー、行列など）を使いたかったため Sphinx を検討してみた。

Sphinx については初めて触ったので、よくわからない状態。

追記：やっぱり YARD を使う感じに。

Sphinx のインストール

$ sudo apt-get install python-sphinx

rubydomain のインストール

API ドキュメント用に py:method や c:function などが最初から用意されています。ですが Ruby 用のは用意されていないため、拡張として公開されている sphinx-contirb/rubydomain をいれます。

$ # easy_install はインストール済とする
$ sudo easy_install -U sphinxcontrib-rubydomain

雛形の作成

適当なディレクトリで

$ sphinx-quickstart

を実行します。プロジェクト名や作者、その他もろもろのことが訊ねられますので、答えていくと雛形が作成されます。

設定ファイルの修正

conf.py を修正します。

ここでは数式用の pngmath と rubydomain を読み込むようにします。

extensions = ['sphinx.ext.pngmath', 'sphinxcontrib.rubydomain']

ドキュメントの記述

最終的にはファイルを分割するのが好ましいのかもしれませんが、とりあえず index.rst に記述します。

.. rb:module:: Celes

.. rb:function:: pfw06(date1, date2)

  Returns the precession angles (IAU 2006 model).

  :param date1: TT as a 2-part Julian Date
  :type  date1: Float
  :param date2: TT as a 2-part Julian Date
  :type  date2: Float
  :rtype: Array
  :return: [*gamb*, *phib*, *psib*, *epsa*] -- see below.
  :raise: TypeError

  Returns
    * *gamb* (Float) -- Fukushima-Williams angle :math:`\bar{\gamma}`
    * *phib* (Float) -- Fukushima-Williams angle :math:`\bar{\phi}`
    * *psib* (Float) -- Fukushima-Williams angle :math:`\bar{\psi}`
    * *epsa* (Float) -- Fukushima-Williams angle :math:`\epsilon_A`

  Example
    .. code-block:: ruby

      Celes::pfw06(2450000.5, 5678.9)
      #=> [5.567146520539624e-06, 0.40906694795782306, 0.002764904877386836, 0.409066897588741]

モジュール関数についての記述です。 rb:module に対してはインデントを用いません。

説明文の中で :param var1: :type var1: などを利用することができます。もちろん用いずにリストなどだけで整形しても構いません（ YARD などに比べるとあまり強力なものではないので）。

などを見るとなんとなくわかるような気になります。

HTML 出力

$ make html

を実行すると（デフォルトだと） _build/html/index.html に出力されます。