実際の用語集で読み仮名を指定する方法を説明いたします。
yogosyu ディレクティブはほぼ glossary と同じ使い方で、読み仮名を付ける方法だけが拡張されています。
glossary ディレクティブに存在する sorted に加えて yomimark オプションを指定下さい。ここで指定した記号を見出し語と読み仮名の分離に使います。
このオプションには、用語そのものと読み仮名のどちらにも使わない一文字を指定します:
.. yogosyu::
:sorted:
:yomimark: 、
yomimark に指定する記号は yogosyu ディレクティブ毎に別々に指定できます。
この例では読点を使っていますが、その他の文字や記号でも構いません。また、単一文字の代わりに space と記述しておくと半角空白を区切りに用いることができます。ただしこの場合、二語以上から成る英熟語を見出し語に使えなくなってしまうので注意してください。
ノート
指定できる記述は docutils.parsers.rst.directives.__init__.py にある single_char_or_whitespace_or_unicode メソッドが解釈できるものです。
space の他には tab や U+hhhh などが使えますが、後者では記述が楽にはなりませんね。
sorted オプションは指定しなくても構いません。その場合は当然ながら索引でだけ並べ替えが行われます。
見出し語、yomimark で指定した文字、読み仮名の順に記すだけです。読み仮名が不要と思われる語は従来どおり見出し語だけで構いません:
.. yogosyu::
:sorted:
:yomimark: 、
姫踊子草、ひめおどりこそう
鈴見咲君高が作成したキー入力入れ替えソフトの名称。
yomimark で指定した文字の前後に余分な空白を入れないでください。また指定した文字が二回以上出てきた場合、それ以降の文字は無視されます。
ノート
複数の読み仮名を一度に付ける需要があるかなぁ、という漠然とした想像の元で今のところそういう設計になっています。
読み仮名の付け方と並べ替えや索引におけるグループ化への影響は使っている sort_order_xx.py の記述内容によります。同梱の sort_order_ja.py をそのまま使う(ことになる)場合は次のように考えてください。
sort_order_ja.py を参考にしてください。
sort_order.py で定義されている sort_order.SortOrderBase クラスを継承し、並べ替え用の文字列を返したりグループ化による先頭文字を返したりするメソッドを実装します。
加えて Sphinx 本体から呼び出されるであろう setup メソッドにて、環境変数 env に当該クラスの実体を保持させます。
このような構造にすることで、先の説明で紹介した方法により新しい並び順が使えるようになります。