reSTおよびSphinxで文章を書く際のtips

Sphinxを使って論文っぽい文章を書くときのtipsをまとめておきます。

追記: この内容は Sphinx逆引き辞典により詳細にして載っています。

用語を書く際はreplaceを使う

.. |hoge| replace:: ほげら

こう定義しておくと次からは |hoge| とするだけで、ほげらと自動的に展開してくれます。つまり、あとからこの用語名を変えたいな、と思ったときにはこの定義のところだけを変えれば勝手に全部入れ替えてくれる、というわけです。

ただし、複数のrstファイルに分けている場合には使えないので、別のファイル(例えばdefinition.txt)に replace を書いておき、

.. include:: definition.txt

と各rstファイルの先頭に書いておきます。この時、.rstではなく.txtなど他の拡張子のファイルに書いていることに注意してください。そうしない、Sphinxがどこからも参照されてない.rstファイルがあるーって怒っちゃいます。

version 1.0以降であれば、rst_prologを使う方法もあります。rst_prologとは各rstファイルの先頭に追加するものを記載する変数です。これを利用する場合、conf.pyに以下のように書きます。

rst_prolog= u"""
.. |hoge| replace:: ほげら
"""

あるいは、includeと組み合わせて

rst_prolog= u"""
.. include:: definition.txt
"""

とか書いてもいいかもしれませんね。

図にキャプションをつける

figureを使います。figureはimageディレクティブに、キャプションなどを付け加えます。

.. figure:: ファイル名
   :scale: 40%
   :alt: Alternate Text (キャプションじゃないよ)
   
   一行あけてここに書いたものがキャプションになります。

と書けばいいのですが、HTMLに書きだした場合,

<p class="caption">

となるにも関わらず、captionというCSSが定義されていないので、普通の文章と同じようになってしまいます。(shimizukawaさん、takanoryさん、ありがとうございます)

章や節に番号を振りたい

1 章、1.1節などのように番号を振りたい場合、toctreeに:numberd:を加えます。

.. toctree::
   :maxdepth: 2
   :numbered:

   overview
   design
   implementation

ただし、章や節に文中から 「1.1節で述べたように」 などとはしてくれないみたいです。(後述の「表に番号を自動で振りたい」も参考のこと)

標準の--や+を使って書くグリッドテーブル方式は非常に書くのが大変です。csvテーブルListテーブルを使った方が楽です。

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
   crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"


.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
表に番号を自動で振りたい

表に自動で番号を割り振って、文中からその番号で参照したい、ということがあります。(例: 図1では…)しかし、

http://stackoverflow.com/questions/2686310/referencing-figures-with-numbers-in-sphinx-and-restructuredtext

を見ると、その機能はまだ実装されていないそうです。残念。

一応やる方法はあって、http://article.gmane.org/gmane.text.docutils.user/5623 によると、refロールとlabelロール、そしてlatexを直接使うそうです。ただし、ぼくの環境(TeXLive2010 on Mac)では、platex的にエラーになりました。

.. role:: ref

.. role:: label

.. raw::  latex

  \newcommand*{\docutilsroleref}{\ref}
  \newcommand*{\docutilsrolelabel}{\label}

.. figure:: mc.png
   :width: 50

   :label:`mc` Midnight Commander icon enlarged 

citation

.. [CITE2011] 出典元

とどこかに書いておき、

[CITE2011]_ とか書いて参照

replace と異なり、複数のrstファイルに分散していても、そのうちの一つのrstファイルで一度定義しておけば大丈夫です。というより、replaceと同じようにincludeしてしまうと、重複して定義していると怒られてしまいます。

refer (Internal Hyperlink)

同じ文書中の他の項や節を参照するには、Internal Hyperlinkを使います。

.. _ex-hoge:

---------------
ほげほげ
---------------

このように、章や節の上に記述して定義する。

--------
他の場所
--------

ほげほげに関しては :ref:`ほげほげ<ex-hoge>` として任意のテキストで参照します。

TODO

conf.pyに

extensions = ['sphinx.ext.todo', 'とかその他の' ]

[extensions]
todo_include_todos=True

としておき、

.. todo:: ブロック図を書く

と書くと、TODOがわかりやすく表示されるようになります。

また、

.. todolist:: 

とすると、全部のrstファイル(というか、TOC Tree)からTODOを探してきて、一覧表示してくれます。TODOを定義したところに飛べたりしますので便利です。index.rstなど目立つところに書いておきましょう。

文章の途中に画像を埋め込む

ymotongpooさんの文章の途中に画像を埋め込むを参考に、imageとreplaceを組み合わせます。

An example of set notation would be |comprehension|.That set notation
tells you the results you want will be all real numbers who are equal
to their own square.

.. |comprehension| image:: img/comprehension.png