Sphinx文書のadmonitionカスタマイズ

Question

###実現したいこと＝質問
Sphinx 初心者ながら、Sphinx ドキュメント（日本語）を構築しています。今はまず html ドキュメントへの変換作業を行っているところです。

sphinx-build の引数として -D language=ja とすることで、自分で記述した文章以外で、所定の箇所も日本語化されています。その中の代表的なものが admonition であり、"warning" は「警告」、"note" は「注釈」と表示されています。

この admonition をカスタマイズして、例えば "warning" は「注意」、"note" は「メモ」といったように変更したいと思っていますが、どこでどのように設定できるのかがわかりません。これを教えていただきたく思います。

例えば docbook-xml、docbook-xsl の場合、XMLファイル内にて lang="ja" を指定して、ja.xsl を読み込むようにすれば、ja.xsl 内にて admonition に対する定義が含まれていて、これをカスタマイズする方法があることを承知しています。こういったことが、Sphinx ドキュメント構築においてできないか、と思っているところです。

ご教示よろしくお願い致します。

Comments

[hotta]

使用 OS と Sphinx のバージョン、およびインストール方法を追記願います。

[matsuand]

Debian 9.1.0、Sphinx (sphinx-build) 1.4.9 です。apt-get install python-sphinx による標準インストール。

Answer 1

強引に（とりあえず）自己解決しました・・・ もっとスマートな方法、ないでしょうか？・・・

sphinx/locale/init.py に以下を発見：

admonitionlabels = {
    'attention': l_('Attention'),
    'caution':   l_('Caution'),
    'danger':    l_('Danger'),
    'error':     l_('Error'),
    'hint':      l_('Hint'),
    'important': l_('Important'),
    'note':      l_('Note'),
    'seealso':   l_('See also'),
    'tip':       l_('Tip'),
    'warning':   l_('Warning'),
}  # type: Dict[unicode, unicode]

sphinx/locale/ja/LC_MESSAGES/sphinx.po に以下：

#: sphinx/locale/__init__.py:198
msgid "Attention"
msgstr "注意"
...
#: sphinx/locale/__init__.py:204
msgid "Note"
msgstr "注釈"

これより強引に、自文書内の conf.py 最終に以下を定義：

from sphinx.locale import admonitionlabels
admonitionlabels['note'] = u'メモ'
admonitionlabels['warning'] = u'注意'

以下の index.rst 文書を処理し、所望の結果を得ました：

テスト
======
.. note:: これは note です。
   デフォルトでは「注釈」と表記されます。
.. warning:: これは warning です。
   デフォルトでは「警告」と表記されます。

もっと標準的な方法ってないのでしょうか・・・

Answer 2

CentOS 7.3 + python-sphinx-1.1.3-11.el7.noarch と少し古い環境ですが、
http://www.sphinx-doc.org/ja/stable/intl.html
の通りにやったらうまくいったようです。
一応ログを載せておきます。

$ sudo pip install sphinx-intl
$ mkdir admonition
$ cd admonition
$ sphinx-quickstart （適当に設定）
$ mkdir -p locale/ja
$ vi conf.py
$ diff -Nu /tmp/conf.py conf.py
--- /tmp/conf.py        2017-09-15 08:45:29.837151366 +0900
+++ conf.py     2017-09-15 08:45:57.780002232 +0900
@@ -64,6 +64,8 @@
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = 'ja'
+locale_dirs = ['locale/']
+gettext_compact = False

 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
$ vi index.rst （"warning" と "note" を追加）
$ make gettext
$ sphinx-intl update -p _build/gettext -l ja
Create: locale/ja/LC_MESSAGES/index.po
$ vi locale/ja/LC_MESSAGES/index.po
$ diff /tmp/index.po locale/ja/LC_MESSAGES/index.po
26c26
< msgstr ""
---
> msgstr "警告だよ"
30c30
< msgstr ""
---
> msgstr "注釈だよ"
（index.po が JIS になっていたので UTF-8 に変換）
$ sphinx-intl build（ 1.2.x 以前の場合のみ必要らしい）
$ make -e SPHINXOPTS="-D language='ja'" html
$ w3m -dump_source _build/html/index.html | grep 警 告
<p>警告だよ</p>

Comments

[matsuand]

質問の趣旨が伝わっていないように思いますが・・・
以下のように index.rst を生成して処理したときに、「注釈」と出力される結果を、例えば「メモ」に変えたい、という質問です。po ファイルの msgid に、msgid "注釈" という行が作り出されますか？ 作られないと思うのですが。

cat > index.rst << "EOF"
テスト
======

.. note:: これは note です。
デフォルトでは「注釈」と表記されます。
EOF