用語を定義したい

replace を使います。

.. |ex1| replace:: 例1

使うときは |ex1| と書きます。

こう定義しておくと次からは|ex1|(実際には両端にスペースが必要)とすると、「例1 」と自動的に展開してくれます。つまり、あとからこの用語名を変えたい、と思ったときにはこの定義だけを変えれば勝手に全部入れ替えてくれる、というわけです。

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

.. include:: definition.txt

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

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

rst_prolog= u"""
.. |ex1| replace:: 例1
"""

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

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

と書くこともできます。