【Sphinx拡張】索引と用語集のかな文字対応

#～かな文字に合わせた表示順とルビ～
「 .. index:: 」「 .. glossary:: 」「 :index: 」で、「 言葉 」を書くところで「 かな|言葉 」「 かな|言葉^オプション 」と書いてください。索引ページで「かな」に応じた表示順になります。

読み仮名の表示にも対応しました。（「 :kana: 」は読み仮名の表示のみ。）

#１．はじめに
主に高校の数学と物理の復習を兼ねて、Sphinxで内容をまとめつつ学習しています。matplotlibディレクティブやmathディレクティブを使って楽しんでいます。

まとめた内容を横断的に俯瞰するためにindex, glossaryディレクティブが便利なんですが、例えば「微分」を例に取ると、索引ページ冒頭に「び」「ひ」と表示されて欲しいですよね。これが「微」と表示されてよろしくない。これをどうにかしたかった。

関連記事

先ずは検索。「Sphinx 索引 日本語」と検索しました。

「Yogosyu」というSphinx拡張を知りますが、使おうと思うと最新のSphinx4.1.2では対応していません。ひとまずエラーなく使えるようにしました。が、索引ページは期待通りに表示されません。アレコレ調べている間に実装アイデアを思い付き、自分なりに満足できる動作になりました。これをSphinx拡張として使えるようにしました。

※Yogosyu以外に先達者はいないと思っていますが、いたら教えてください
※先達者を確認した場合は、当記事先頭に「後日談」を追記して報告します。

#２．セットアップ

1. pip install sphinxcontrib.kana_text でインストール。
2. conf.pyに設定追加
3. make kana の実行。 make html ではないので注意。
   • make html にしたい場合はソースの name = 'kana' を変更することで対応可能です。
   • 合わせてadd_builderの第二引数に True を設定してください。

conf.pyの設定

extensions = [
    'sphinxcontrib.kana_text',
]

#html_kana_text_on_genindex = True

• 他にもパラメータはありますが、最初はこれくらいでOKです。
• テンプレートファイルの準備が必要なので、コメントにしておいてください。

#３．使い方

基本的な使い方

関係するディレクティブは index, glossary 、関連するロールは :index:, :kana: になります。

先ずは次の通りに使って、慣れてきたら読み仮名の表示へと手を広げてください。

• 「び|微分積分」と、かなを一文字を付与。

読み仮名の表示

読み仮名の表示は次の通り

• 「 たなかはなこ|田中はな子^ 」、もしくは「 たなかはなこ|田中はな子^12b1 」とする。
• 読み仮名の部分的な非表示は、「a-i」もしくは「q-y」で文字数を指定。

「pair」が結構強力です。数学なら「pair: ひ|微分積分; さ|三角関数」と索引を作ると効果がわかります。一つの「.. index::」に複数の「single/pair/triple/see/seealso」が指定できます。

索引ページでの読み仮名の表示

索引ページでも読み仮名を表示させる時の対応

1. 次の通りにコマンドを実行する

sphinx-kana-genindex
mv genindex.html.sample path_to_sphinx_project/_templates/genindex.html

1. html_kana_text_on_genindex = True とする。

glossaryでは「用語 : 分類名」と記載することで、索引ページでは同じ分類名でまとめることができます。索引ページを「上段、本体、下段」に分けて、上段でアピールしたい用語、本体からは外して下段にこっそり置きたい用語について利用を検討してください。分類名にも読みが設定できるので、これを利用して表示順の調整に使うことができます。（Sphinxでは「実験的な扱い」と説明していますが、その理由と思われるものをFAQに記載しました。）

その他、親切ではありませんが、docstringに書いてあります。

サンプル

###📓rstファイル

サンプル
========
.. glossary::

   び|微分
     距離の関数から速度の関数、速度の関数から加速度の関数を導く.

   せ|積分
     加速度の関数から速度の関数、速度の関数から距離の関数を導く.

   たなかはなこ|田中はな子^12aa1
     読み仮名の表示の確認のサンプル.

     例） :index:`たなかはなこ|田中はな子^12b1`

     例） :index:`たなかはなこ|田中はな子^12qq1<pair: し|架空の小説; て|お試し>`

     例） :kana:`たなかはなこ|田中はな子^12aa1`

.. index::
   pair: かなの表示; き|記載方法

記載例

- 例えば、 :index:`たなかはなこ|田中はな子^12b1` と書くと、索引に記載される.
- 更に、 :index:`たなかはなこ|田中はな子^12qq1<pair: し|架空の小説; て|お試し>` と書くこともできる.
- 索引の表示が不要であれば、 :kana:`たなかはなこ|田中はな子^12aa1` と書く.

###📓できあがったウェブページ
html_theme = 'nature'

###📓索引ページ（冒頭）

###📓索引ページ（「モジュール」）

#４．ＦＡＱ

🐶かなが消えない。

Q: 読みが消えません。「 かな|言葉 」がそのまま表示されます。
A: make html ではなく、 make kana と実行してください。

name = 'kana' と add_builder() の箇所を直すだけ。それぞれでHTMLを出力させて比較ができます。

🙀ルビが表示されない

Q: ルビが表示されない。「 かな|言葉 」と書いたのに、「 言葉 」と表示される。
A: 「 たなかはなこ|田中はな子^ 」と末尾に「 ^ 」を付記してください。

「 た|田中はな子 」とソート用に１文字指定する利用があるので、読み仮名があるだけの場合は非表示にしています。

🐄同じ言葉が別々に表示

Q: 同じ「微分積分」が別々に表示される。
A: 「single/pair/triple」が間違っていないか確認してください。

それでも直らないようであれば、現象を確認できるディレクティブの記載方法を教えてください。「.. index::」の行と続く「single/pair/triple」が書かれた行だけで十分です。

内部処理では「かなかな|言葉」「かなここ|言葉」のように読みが異なると別のものとして処理されます。 html_kana_text_use_own_indexer 設定時はやりくりできるので対処しましたが、不完全かもしれません。

🐎不具合の報告

Q: 不具合の質問は、どうすればいいですか？
A: sphinxcontrib.kana_text とタグを付けて質問を投稿してください。

質問にテストケースがあると喜びます。

#５．開発環境

• Windows10/cygwin64
• pip 21.2.4
• Sphinx 4.2.0

Sphinx 4.1.2 で作りましたが、さっき pip --upgrade sphinx したらアップグレードしてくれやがりました。 4.2.0でもエラーなくmakeができることを確認しました。

glossaryディレクティブの次の説明から、1.4以降ならイケる気がしていますが未確認です。

バージョン 1.4 で変更: Index key for glossary term should be considered experimental.

Python3対応のバージョンがいつからは知りませんが、そのバージョン以降かもしれません。

ソースコードはこちら

以上

version: 0.20.1.5