sphinxcontrib.kana_textを使った索引ページの改善

[KaKkouo]

自作したsphinxcontrib.kana_textを使って、索引ページを改善してみました。

索引ページを見て直せそうなところを独自判断で変更しているので、お手すきの時に確認していただければと思います。

1. https://github.com/KaKkouo/sphinx-users.jp をgit cloneする
2. pip install sphindexer sphinxcontrib.kana_text で二つのパッケージをインストール
3. make html を実行
4. 索引ページの確認

• 大筋で問題なければ、修正点を教えてください。こちらで直します。

※不採用は不採用でしょうがないので、その時は簡単に理由などを教えていただければ・・・

変更点など

• 読み仮名に対応していないために英字を使っていたと思われる箇所を一通り変更しています。
• index/glossaryディレクティブで直接読み仮名情報を付与できますが、記法が独自形式なので辞書ファイル（のようなもの）に読み仮名情報を集約しています。

参考（索引ページのスナップショット）

<その1>

<その2>

その他

• 当パッケージでは日本語の使用を想定しているので、string.startswith('\N{RIGHT-TO-LEFT MARK}') のような判定は入れていません。
• _('Symboles') の対応も現状は入れていませんが、「これは入れるべきかなぁ、、」と考えています。
• shimizukawaさんには（stackoverflowで、かなり）お世話になっています。ありがとうございます。

以上、よろしくお願いします。

[KaKkouo]

追記

• requirements.txtの追記を確認しました。
  • gitがまだ不慣れで入れ違いになっていました。すいません。
  • sphindexer も必要なので追記しました。
    • 将来的にはこれが不要となるように、現在本家でpull reqeust して働きかけています。
      • 現在評価中なので、どうなるかはわかりません。
    • 該当機能のアルゴリズムの変更を提案しているので、期待している結果になるとしても確認には時間がかかると予想しています。
• security/snykがfailになっていますが、分かっていないので触っていません。
  • ローカルで実行する make html はエラーにならないことを確認しています。

[KaKkouo]

追記（分類子の並び順）

sphinxcontrib.kana_textのロジックを調整して、分類子（便宜上、この呼称を使います。glossaryのコードで見つけた呼称です）の並び順を変更してみました。

• とりあえず、「分類子に限定して」「一文字表示のみ」の場合に並び順を変えています。
  • 元に戻すことも可能です。今のところは予定していませんが、「設定で調整する」も対応可能です。
• index_keyを指定した場合は（現状は）全て先頭寄りで表示されますが、調整する予定です。
  • 「読み仮名を含む、内部表現での分類子の文字列が二文字以上」を「index_keyが指定された場合」と判断します。

[usaturn]

pull request ありがとうございます。
近々、ハッカソンがありますので、その際に確認させてもらいます。

[KaKkouo]

ご連絡ありがとうございます。

散らかっていて申し訳ないのですが、必要に応じて使ってください。

• https://kana-text.readthedocs.io/en/latest/
• https://sphindexer.readthedocs.io/en/latest/
  • 日本語に特化しない部分はこちらになります。
• ソースコードにも要所要所でコメントを書いています。

※「ないよりはマシ」くらいに思ってください。

[usaturn]

@KaKkouo
ひとまず、branch を checkout して新規の venv に pip install -r requirements.txt を実行しましたが、下記のエラーがでます。
可能でしたら修正お願いします。

  Downloading sphindexer-0.5.1.tar.gz (9.9 kB)
  Preparing metadata (setup.py) ... error
  ERROR: Command errored out with exit status 1:
   command: /home/usaturn/.venv/sphinxjp/bin/python -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-install-t1sjr70x/sphindexer_1edecdaeb09f4451a978190901baba58/setup.py'"'"'; __file__='"'"'/tmp/pip-install-t1sjr70x/sphindexer_1edecdaeb09f4451a978190901baba58/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-pip-egg-info-9tzvh6xg
       cwd: /tmp/pip-install-t1sjr70x/sphindexer_1edecdaeb09f4451a978190901baba58/
  Complete output (7 lines):
  Traceback (most recent call last):
    File "<string>", line 1, in <module>
    File "/tmp/pip-install-t1sjr70x/sphindexer_1edecdaeb09f4451a978190901baba58/setup.py", line 4, in <module>
      import src as si
    File "/tmp/pip-install-t1sjr70x/sphindexer_1edecdaeb09f4451a978190901baba58/src/__init__.py", line 18, in <module>
      from docutils import nodes
  ModuleNotFoundError: No module named 'docutils'
  ----------------------------------------
WARNING: Discarding https://files.pythonhosted.org/packages/b5/f1/9b4aeb4d8b72d23d8e04e18d473ff0081dee3e5a106a7e2f0953af4ae473/sphindexer-0.5.1.tar.gz#sha256=08097640af97070b26ca921bea609e3d9470b93cba33cc30eb3a82ba39df52cf (from https://pypi.org/simple/sphindexer/). Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.
ERROR: Could not find a version that satisfies the requirement sphindexer (from versions: 0.5.1, 0.5.2, 0.5.3, 0.5.4, 0.5.4.2, 0.5.5, 0.6.0, 0.7.0, 0.8.0, 0.9.0, 0.10.0, 0.10.1, 0.10.2)
ERROR: No matching distribution found for sphindexer

[KaKkouo]

@usaturn
ご確認ありがとうございます。

申し訳ないのですが環境構築についてはまだ不慣れでして、、分かるのは次の二点です。

• sphindexerは0.10.2がインストールされるべきなのに0.5.2のインストールでエラーになっている
• docuitlsはSphinxインストール時に依存関係でインストールされるべき

恐らくですが sphinxcontrib.kana_text が依存する sphindexer のインストールを上手く処理できていないものと考えられます。sphindexer 0.10.2（現状の最新版）がインストールされるのが期待する動作です。

こちらでも試行錯誤してみますが、上記二点からrequirements.txtの記載内容が修正できるのであれば助かります。

[usaturn]

@KaKkouo 失礼しました。エラーログは一番下の行しか書いてなかったのですが、以下のコマンド結果を載せますね。

 pip install sphindexer 2&> install_sphindexer.log

0.10.2のダウンロードに失敗して徐々にバージョンを下げてダウンロードを試しているように見えます。
install_sphindexer.log

[tk0miya]

sphindexer は setup.py の中で import src しているため、パッケージをインストールするのに Sphinx や docutils を必要としています。
https://github.com/KaKkouo/sphindexer/blob/e71d94f012e4e5b14ce5ad8a5ec05300d3b0c815/setup.py#L7-L10

pip install -r requirements.txt する前に pip install docutils Sphinx するとインストールに成功しますが、これは意図した状態ではないですよね。

一般的には setup.py の中でライブラリのコードを読むのは推奨されていないやり方です。
setup.py に直接書くようにしてもらえますか。

※ 実行時にバージョン情報を参照できるように、変数に入れる方法は世の中にいくつか存在するようです。ここでは紹介しませんが、興味があれば調べてみてください。

ちなみに Sphinx 本体の方に送っていただいた PR の方はなかなかみる時間が取れていないので、リアクションできずにいて申し訳ないです。緊急バグフィックス版の 4.3.1 がリリースできたので、他のイシューを整理しながらみる時間を確保しようと思います。申し訳ないですが気長にお待ち下さい。

[usaturn]

また make kana の出力結果(下記パスのローカルファイル)を確認しても上記のスクリーンショット通りにならず、 make html の結果と同じになっています。
sphinx-users.jp/_build/html/genindex.html
失礼しました。きちんと出力されていました。
ちょっと気になったのが、「中」と「設」が意図通りではないかなと思いました。

[KaKkouo]

sphinxのインストール（install_sphindexer.log, setup.py）

確認ありがとうございます。
ご指摘の点については確認して直します。

※setup.pyの記述について理解が追いついていないため、時間が掛かります。
　既に対応されていて助かっていますが、ハッカソンまでには間に合わない前提でいていただけると助かります。

PR

一から作ってしまっているのでまとまった時間が必要ということは承知しております。
（お手数をおかけすることになってしまい申し訳ないです）

setup.pyだけでなくpytest用のテストケースもそうなのですが、ちょこちょこと不勉強な故の我流の部分があります。
restructuredtext.parse(app, text) を活用しておらず我流になっていますが、これも「対応予定」を前提として見ていただければ助かります。何か不明な点があればご遠慮なくどうぞ。

（追記）
あちらに書きましたが、restructuredtext.parseで此方の想定する状況を創出する方法が分からなかったため、できる範囲でコードを整理しました。

「中」「設」について

直接には次の二点が原因です。

• 「中」…辞書ファイルのようなもの（word_list.txt）に読み情報が登録されていない。
• 「設」…該当する「.. index::」での記述の間違い。
  • 加えて「読み情報が登録されていない」状態のようです。

中途半端な状態で git commit してしまっていたのですが、恐らくそれが使われているのだと思います。すいません。

正しく解決はしていないのですが sphindexer の件で requirement.txt の更新を git push しているので、KaKkouo / sphinx-users.jp とローカルの差分はなくなっておりご指摘の問題はローカルでは解消されています。お手数ですが確認いただけますでしょうか。

追記）「中」「設」について、ローカル環境での状況

[KaKkouo]

追記）sphindexerのインストールエラーについての対処内容

setup.py中の import src を削除、これに依存していた情報について setup.cfg に記載しました。
これにともない sphindexer 0.10.2.1 が最新になっています。

• sphinxcontrib.kana_text の readthedocsコンテンツは sphindexer を個別にインストールしていましたが 、この個別のインストールの記述を削除してもエラーなく構築されていることは確認しました。
  • ただ、これが「修正確認」となっているのか自信がありません。
• 本PRについて 便宜上 word_list.txt を更新して git push して security / snyk 処理を起こしましたが、こちらの failed は解決しませんでした。

備考）word_file.txtについて

.. glossary::、.. index:: に書かれた文字列について、どんなに長い文字列でも「一つの単語」として処理しています。
そのため「word_file.txt」の記載内容が感覚的に宜しくない記載になっています。

• 分かち書きなどの対処は大掛かり過ぎるので考えていませんが、現在の「表記文字列に対する完全一致」に加えて「表記文字列に対する前方一致」については対応を考えています。
  • あくまでもpythonの辞書で対応できる範囲内で、ですが。

これとあわせて「かな情報の適用の優先順位」も調整する予定です。現状は「word_list.txtのみにかな情報を記載」となっているため、この「優先順位の調整」の影響はありません。かな文字情報の現在の記法への依存性を弱めておくのであれば、一括変換がしやすい「word_list.txtに集約」のままがいいと思います。

• 都度ファイルに書くよりも、直接かな文字情報を書いてしまうのが楽なのは確かです。
• 索引ページのでの並び順についてはかな文字情報は1文字だけでも十分目的を達成することが可能で、例えば「設定（conf.py）」なら「せ|設定（conf.py）」でも事足ります。この時、「せ|用語」が複数ある場合は「用語」の文字コードに依存した並び順になります。
• ルビ表示させたい場合はかな文字情報を全て記入する必要があります。

[KaKkouo]

「中」「設」の対処

原因究明についてはさておいて、手っ取り早く対処するのであれば次の通りです。

1. 「中」「設」の該当箇所を特定する。
   • source/reverse-dict/system/doctree.rst
   • source/reverse-dict/pdf/font.rst
2. 直す。（すいません）
   • 「中」については「ち|中間ファイル…」と先頭に1文字読みを付記すれば事足ります。
     • 前後の「注釈」「注意」との並び順が変わって「注」「中」の文字コードでの並び順になります。
   • 「設」については「 single :が未記入」とか「セミコロンの前後の空白の有無」だったはずです。
3. make htmlの実行

[KaKkouo]

security/snykについて

PRで表示されているfailについては確認しようとすると「organizationうんたら」と表示され、料金なことや権限管理などの判断が必要になると思われ、クリックないようにしています。

アカウントが無料で作れることが分かったのでアカウントを作って、この環境に直接リポジトリをインポートして判定結果を確認しました。Sphinx関連のエラーではなく環境構築に関連したエラーのようです。

Critial/Highを添付しておきます。

その他はざっと見た程度ですが、Sphinx関連のエラーは見当たりませんでした。

[tk0miya]

反応がかなり遅くなってしまいました。申し訳ないです。
送っていただいた内容と kana_text 拡張の内容を確認しました (コードは流し読み程度ですが…)。

index/glossaryディレクティブで直接読み仮名情報を付与できますが、記法が独自形式なので辞書ファイル（のようなもの）に読み仮名情報を集約しています。

この点について確認させてください。kana_text が目指している方向は、インラインに書くやり方のように見えたのですが、今回の PR では、上のコメントにあるように辞書ファイルの定義となっています。
Sphinx 本体に PR を送っていただいたように、将来的な展望としてはインラインに書く方式を狙っているのでしょうか。

今回の修正が Sphinx 本体に修正が取り込まれるまでの一時的なものなのか、継続的なものなのかが気になりました。

また、少し脱線しますが、kana_text はルビなども含めた総合的な日本語化を目指した拡張をゴールとしているようなので、どのように Sphinx に取り込んでいくのかは悩ましいところがあるなと思っています。
Sphinx に送っていただいた PR は現状の kana_text とも異なる記法 (現状の glossary に合わせた : ベースのもの) になっており、最終形がどうなるのかなというのが気になっています。

辞書形式とインライン形式、どちらが扱いやすいのかは正直自信が持てていません。
辞書形式の場合は二重管理になってしまうため、メンテが大変そうだな、というのが初見の感想です。
一方で、マークアップの形式が標準と変わらないため、互換性については考えることが少なくて良さそうだなとも思っています。
(さらにいうと、mecab などの標準的な辞書を使った動的な読みの解決などといったアイディアもありそうなので、この部分は壮大過ぎてまだ自分の想像が追いついていないというのが正直な感想です)

いろいろと書いてしまったのですが、いま感じているのは以下のものです。

• 現在の Sphinx は、日本語のインデックス管理に問題があるのは確かなので、最終形を意識するがあまり、読者に不便を強いるのは望ましくない。
  • 短期的な解決方法と長期的な解決方法に分けて議論を進めたい
  • とはいえ、明らかに未来がないものを導入するのも避けたい
  • 今回、sphinx-users.jp に導入するのは辞書形式なのか、インライン形式なのか
• sphinx-users.jp は HTML への変換さえ考慮しておけば良いので、他形式については考えなくてよいだろう
  • そのため、PDF などの変換に影響があるか、と言った観点ではチェックしていません。

1月の Sphinx Hack-a-thon で @shimizukawa と議論した上で書いたものです。不足があったら捕捉ください > @shimizukawa (忙しい場合は slack でも口頭でもよいので…)

[shimizukawa]

はい。 sphinx-users.jp サイトへのPRの範疇については補足とくにありません。

Sphinx本体としては、 index, glossary あたりの索引登録まわりを拡張で取り扱いやすく整備したうえで、日本語固有部分は拡張に任せられるようにする、といった方向にできるとよさそうと思います。

[KaKkouo]

ご確認ありがとうございます。
わかりにくいところがあったようで、申し訳ありません。

パッケージは二段構成（sphinxcontrib.kana_text, sphindexer）になっています。

sphinx-users.jp のPRで取り上げているkana_textについてはSphinx本体への取り込みは考えていません。
Sphinx本体に取り込んで欲しいのは、sphindexerにある（kana_textのための）拡張性までです。
拡張性の対応には現在のindexentriesのアルゴリズムの置き換えが含まれます。

「表記文字列とは別に読み情報がある」という概念は日本独自のものと考えていて、
日本独自部分も込みでSphinx本体に取り込むのはSphinx開発側としては厳しいと見ていました。
このため、Sphinx本体に取り込んで欲しいと思っている機能に相当するsphindexerについては、
拡張性のために必要な部分を除いて日本語独自のものは取り除いています。

以下、パッケージの説明です。パッケージの後にQ&Aを書きました。

ご質問、気にされていることを網羅したつもりですが、
「頭の中にあることを吐き出した」感じで分かりやすい構成となっている自信はありません。
気になることがあれば遠慮なく。

整理してから質問するのもアレでしょうから、ふと疑問に思ったことは都度kana_textプロジェクトの方にissueを挙げてください。GitHubの利用歴が浅いので、この点で何か流儀があるなら従うつもりでいます。Stackoverflowでも。
⇒全体像がつかめて来たらWikiでまとめるなど。

---

パッケージsphindexer

本体に取り込んで欲しい内容に相当するもの。
現状PRしているものと、以降に予定しているものを含みます。

• 現在のPRはindexentriesの差し替えのみで、PRしているindexrackは拡張性は持ちますが日本語対応そのものは含みません。
• index/glossaryの対応は現在PRしていませんが、拡張性の対応はする予定です。
  • 拡張性のみだと説得力がないかなぁ、と思っていてglossaryにclassifierというオプションを追加する予定です。
• kana_textを意識した拡張性をSphinx本体に入れたいと思っていますが、kana_textそのものは本体に入れることは考えていません。
• see/seealsoについて
  • Q:他の用語とは独立して表示順を決めていますが、現仕様の混在のままがいいでしょうか？
  • Q:see/seealsoの違いは現状文言のみですが、どう使い分けるものなのでしょうか？
  • 索引ページでの「同一ページ内リンク」まで対応したいと思っています。

パッケージshpinxcontib.kana_text

こちらは本体への取り込みは考えていません。

• 読み情報の解析は「KanaTextクラス」に集約して、ここで記法の対応をしています。
  • kana_textはリファレンス実装として位置付けた方がいいような気がします。「KanaText」部分を独自に実装すれば、異なる記法での「読み情報」の記載ができるようにしています。
  • 実情がわからないのですが、「読み」の概念があるのなら中国語でもイケるはずです。
• kana_textで採用している記法は言ってみれば私の好みなので、sphinx-users.jpで採用する記法とするのは抵抗があります。そのため、記法が変わっても対応しやすいように辞書側に持たせています。
  • 現状の機能としては「辞書、インライン」の両方に対応しますが、「原則として『辞書』で一括で対応。同じ表記だけど特定箇所の用語だけ読みが変わるような場合はインラインで個別対応」がrstのメンテナンスとしては楽なのでは？と思っています。
    • 現状の記法の一長一短を理解していただければ、sphinx-users.jpとしての記法が決まるような気がします。
  • 現状の記法は「索引ページでの表示」が重視されており、ルビ表示はこだわるほど設定が面倒になっていきます。
    • ルビ表示を必須としなければ、例えば「墾田永年私財法」も「こん|墾田永年私財法」と２文字くらいあれば表示順としては十分です。
    • 一方でこれをベースとすると、索引ページでの表示順を満足しつつも「ご丁寧にありがとうございます」のようなパターンのルビ表示が悩ましくなります。
    • ルビの表示・非表示を丁寧に指定できるようにしていますが、不備を見つけたので現状のルビ表示の詳細指定のロジックは一部見直す予定です。

補足的なこと

• kana_textでの「（索引ページ以外の）rstファイルに対応した通常ページ」の現状の対応は、入力部（index/glossaryディレクティブ）ではなく出力側（HTML5Translator）でやっています。ただ、これは綺麗な対応ではないと思っています。
  • これの対応をするには、前段としてindex/glossaryディレクティブに拡張性を入れ込む必要があります。
  • TextElementに介入できればコードがもっと綺麗になると思うのですが躊躇しています。
• Text/TextElementクラスについて
  • KanaTextクラスはdocutilsのTextクラスの拡張版となっており、「既存のTextクラスをどこで差し替えるか」というのが実装上の課題になります。
  • Glossaryクラスを見ていて気付いたのですが、TextElementって問答無用でTextクラスを使うようになっています。
    • TextElementクラス内でTextクラス以外のクラスへの差し替えが容易になるような仕掛けを入れたいのですが、docutilsにまで手を広げるのは心象的にハードルがとても高いです。
    • このため今やっているGlossaryクラスでの日本語対応のための土台の整備は、これを迂回するような書き方になっています。
• 個人的には「『なろう』や『カクヨム』でも使えるツール」が目標です。
  • 小説での表記は「空行なしの改行」「空行一つ」「空行二つ」辺りがreST独自の記法となってしましい、微妙ですが。。
  • 微妙な点が受け入れられるなら、glossary/indexを駆使して、「登場人物や用語」の管理ができるかなぁ・・・と思っていまして
  • 小説を書く人では全くないので需要があるかどうかはわかりません。

---

Q&Aの前に

提案的な要点

• kana_textは日本語対応の拡張パッケージとして、Sphinx本体には取り込まない。
• Sphinx本体には日本語対応の拡張パッケージのための拡張性を持たせる。
• 日本語対応の拡張パッケージは、「kana_text」以外にも登場することを想定しておく。
• sphix-users.jpとしての現状は、「暫定対応」として索引ページ重視のkana_textを採用。

要点の補足

• Sphinx本体と拡張の役割分担は次のイメージ
  • 拡張パッケージとしてkana_textで日本語対応
  • 日本語対応のために必要な拡張性をSphinx本体で持つ
• 辞書形式、インライン式
  • 辞書形式のみ、インライン式のみ、両方どれでも対応は可能。
  • 実装として楽なのはインライン式のみですが、index/glossaryの両方を使う場合は「同じ用語」が複数箇所に書かれるので、その場合、一括で設定できる辞書形式は設定が楽。
• よみがな情報を付与する記法
  • 現状の記法は「索引ページでの表示順重視」で、ルビ表示もできますが「ルビ表示は使わない」と割り切れば作業は楽。
    • 私は愛着もあるので現在の記法が好きです。
    • sphinx-users.jp側ステータスとしては「要検討」とするのが無難だと思っています。
      • kana_textの利用は現状は「暫定対応」と考えて、「辞書形式を使用」「ルビ表示未使用」とするのが変更があった場合の対応としては楽だと思います。この場合は変更後も「辞書形式」が想定されますが、インライン式だった場合より対応が楽です。
    • 辞書形式、インラインどちらであっても、ミスは索引ページで分かるのでチェックは思ったほど大変ではありません。
  • 「現在のkana_textをパクって、記法だけ別途」がやりやすいように、記法部分は「KanaTextクラス」に収めている。
• 記法の方向性について
  • 「索引ページの表示順巡視」「通常ページでのルビ表示重視」「割り切って別々に実装する」「その他」などがあります。
  • 言い換えると、sphinx-users.jpとしては「ここが決まっていない」と同時に「決まっていないのはここだけ」とも言えます（私見）。
  • これに異論がなければ、「記法の解析に依存した部分をKanaTextに集約」という実装仕様自体は問題がなく、「記法に選択肢を与えてkana_textパッケージは拡張とする。indexrack.pyなどのsphindexer相当の部分はSphinx本体に取り込み」というバランスは妥当じゃないかと考えています。辞書形式・インライン式自体は記法についての方針が決まれば決まるので、例えば第二第三のkana_textパッケージが登場するようなことがあれば、「それぞれにお任せでいいのでは？」くらいの理解です。

Q&A

Q1：Sphinx 本体に PR を送っていただいたように、将来的な展望としてはインラインに書く方式を狙っているのでしょうか。
A１：Sphinx本体のPRではkana_textがカバーする機能の取り込みは予定していません。

Sphinx本体へのPRは、あくまでも拡張性までであって読み情報に対応した実際の拡張は含みません。
英語の説明がアレで誤解させてしまったのかもしれません。ごめんなさい。
（「拡張性」と「拡張」が区別できる英単語になっていないのかもしれません）

誤解をさせてしまう箇所を教えてください。直します。
（ただ、英語力がアレで直しても誤解させるままの表現になってしまうかも・・）

元々の実装の経緯としては以下の通りで、実装都合としてはインラインの方が楽です。
　１．本来の表記文字列に対して「よみ情報|表記文字列」とすれば、索引ページで並び順がいい感じになる
　　　→表示処理の手前で「よみ情報|」を除けば表示もOK
　２．やっていくうちにIndexEntriesクラスの限界に直面して、（機能的には）しばらく停滞
　３．テストケースライブラリの勉強を兼ねてIndexEntriesの入力/出力を見たことで、IndexEntriesの処理内容を理解。
　　　→個人的に慣れている処理パターンが使える範疇だったので着手
　　　→クラスにすることで使い勝手も良くなった（主観）
　４．「同じ用語」が複数箇所にある場合の記入が不便で、これに対処する実装を加える
　　　→あとで気づいたのですが、glossaryで指定する「用語」はドキュメント内で一意ではないと駄目なようですね。。
　　　→indexディレクティブも含めて複数の同じ「用語」がある場合の、各場所で読み情報の記入を省く機能として
　　　　→「Sphinxの機能仕様としては実は要らない」などあれば教えてください。
　５．kana_textを「日本語対応」「そのための拡張性」に分離。後者をsphinxdexerに。
　６．４の機能を利用して辞書形式の機能を追加

私自身は「実装都合ならインライン式」「rstファイル編集都合なら辞書形式」と思ってますので、この辺りは認識のすり合わせが必要だと思います。

Q２：Sphinx に送っていただいた PR は現状の kana_text とも異なる記法 (現状の glossary に合わせた : ベースのもの) になっており、最終形がどうなるのかなというのが気になっています。
A２：「：」で表現しているものは読みではなく分類子（classifierとか、index_keyと呼ばれるもの）です。

現在の索引ページでは用語に漢字があると、例えば「用語」なら「用」がページ上部に表示されます。
これを「あ」「か」もしくは「あ」「い」「う」での表示に変える（※だたし、これは kana_textの対応）と同時に、
任意のカテゴリを作れるようにしています。

例えば高校物理のドキュメントなら各用語は「あ」「か」などのカテゴリで分類すると同時に、単位系だけ「記号」とは別に分類することができるようにしています。（すいません、今いい感じの具体例が思い付きません）

Q３：一方で、マークアップの形式が標準と変わらないため、互換性については考えることが少なくて良さそうだなとも思っています。
A３：誤解している可能性があります。「：（ころん）」は分類子用のセパレータで、読み情報ようの記号は「|」「^」の二つです。

お手数を掛けて申し訳ないのですが、「分類子」と「読み情報」の違いに注意して確認していただいてもいいでしょうか。

例１）よみ情報のない「用語」であれば「用」が分類子として使われます。
例２）よみ情報がある場合は、「よ」もしくは「や」が分類子として使われます。
例３）分類子を指定することもでき、この場合は分類子に便宜上設定する「よみ」で分類子同士の表示順がきまります。
　⇒これはKanaTextのassortが挙動を握っています。
　⇒IndexRackのsort_unitsでそのことが確認できます。

Q４：今回、sphinx-users.jp に導入するのは辞書形式なのか、インライン形式なのか
A４：実装としては両方対応しているが、sphinx-users.jpとして採用する記法が確定的ではないので辞書型式のみにする方が望ましい。

具体例は思いつかないのですが、「表記は同じでも読みが変わるケース」ってありませんでしたっけ？
辞書利用に限定すると「同じ文字で異なる読み」には対応できませんが、記法が確定的なるまでの暫定としては十分だと思います。

「表記は同じでも読みが変わるケース」がなければ辞書形式のみで問題ないですし、
一括で指摘できるのでこちらがいいと思います（個人的な見解）。

辞書型式の方が「index/glossary」双方に適用されるので、一括の設定としては此方が楽です。
「複数のglossaryがあってもドキュメント内での”用語”は一意」という仕様に気付いていなかったので、
他にもindex/glossaryで分かっていないことがあるかもしれません。

※書いていて気付いたのですが、「indexディレクティブについては、glossaryで指定した読みに従う。ただし、indexディレクティブで読みが指定してあればそれが優先される」というのがいいのかもしれないですね。これならインライン式且つ一括管理にもなります。
※「読み情報」の優先度を「indexディレクティブ>glossary>辞書ファイル」に変更すれば、現状のPRを採用しつつも段階的な対応はできると思います。現在の優先度は辞書ファイルが一番になっています。

Q５：さらにいうと、mecab などの標準的な辞書を使った動的な読みの解決などといったアイディアも
A５：mecabについては今のところ考えていません。

https://kana-text.readthedocs.io/en/latest/
こちらの「実装アイデア」で茶筅に触れていますが、
これのことでしたら「茶筅を使うことなく、茶筅にどこまで届くか」という意味合いで書きました。
（誤解させたようでしたら、ごめんなさい。他の箇所のことだったら教えください）

タラレバの話になりますが、実装するとしたらこんなイメージです。

• KanaTextクラスの入れ替えになるので、拡張パッケージそのものを分けたほうがいいような気がする。
• 読み情報の入力が不要になるはず（憶測）なので、今の辞書形式の方が対応が楽（想像）。

実際には次の点で実装は考えていません。逆に言えばこれらの懸念が払拭されるか、それ以上のメリットがあればわかりません。

• sphinxとsphinx用に作られたパッケージ以外に依存パッケージを増やしたくない。
• mecabを使ったらパフォーマンスが悪くなるような気がする（想像）
  • indexrackで内部データをSQLiteにして見たら、体感で５～８倍くらい時間が掛かるようになりました（うろ覚え）
• mecabで対応している単語ならいいが、対応していない場合はmecabの辞書ファイルの編集が必要（学習コスト）
• mecabなどで「読み情報」の入力が省けるのは魅力だろうけど、現状の「索引ページ」のデータ量は致命的な規模ではない。

まとめると「index/glossaryの利用が進んで、索引ページの規模がある程度以上になるのが当たり前になった頃」に具体的に考える話だと思います（書いていて、そう思ってきました）。

Q６：短期的な解決方法と長期的な解決方法に分けて議論を進めたい。とはいえ、明らかに未来がないものを導入するのも避けたい
A６：日本語（というよりも読み情報の付与）そのものの対応と、その拡張性を分けて考える（※私の見解）。

前者（特に記法）が暫定対応、後者が恒久対応と見ています。
そのため、（Sphinx本体でPRしている）indexrack.pyの評価が重要になります。

indexrack.pyがカバーする機能は拡張性までであり、日本語対応は含みません。

indexrack,pyのテストケースは「実は要らなかったんじゃ…」という内容も含めて、
思いつく限りのテストパターンを入れています。このテストケースで担保して、
ガンガン改良を加えてきたので、個人的にはロジックよりもこちらを見てもらうと安心できます。

Q７：そのため、PDF などの変換に影響があるか、と言った観点ではチェックしていません。
A７：ｐｄｆへの影響はありません。対応するのであればLaTexでの「索引ページ」の機能次第。

表示処理については、HTML5Translatorのvisit_Text/depart_Textを調整しています。
このためHTML以外には影響がありません。

逆に対応するのであれば、たぶんLatexTranslatorクラスがあると想像しているのですが、
これにあるvisit_Text/depart_TextをいじればOKです。
KanaTextクラス側はaslatexを作ることになります。

索引ページはHTML用のBuilderにあり、これしかいじっていませんん。

LaTeX版での「索引ページの用語から対応ページにジャンプする記法」がわかれば、LaTeXでもイケるような気がします。
（分かれば…）基礎的なものは作りますが、見栄えを含めた仕上げについては私のモチベーションの対象外です。

Q８：Sphinx本体としては、 index, glossary あたりの索引登録まわりを拡張で取り扱いやすく整備したうえで、日本語固有部分は拡張に任せられるようにする、といった方向にできるとよさそうと思います。
A８：日本語固有部分はkana_textパッケージで、「拡張で取り扱いやすく整備」はsphinxdexeパッケージとで分けています。

sphindexerパッケージは対応する機能の全てがSphinx本体に取り込まれれば、役目を終えるパッケージです。

現状、Sphinx本体PRとしてはindexrack.pyのみですが、index/glossaryも予定しています。
glossaryについては作っていますが、まだPRしていません。

glossaryではコロン（：）を使って「分類子（classifierもしくは index_key）」が指定できるのですが、
これを使った時の現状のindexentriesに問題があり、glossary編集後は毎回「make clean」してからでないと索引ページが崩れます。

あと、単純に「Glossaryクラス（改）」のカバレッジが思うように上げられなくて悩んでいます。
（動作そのものは特に問題はないのですが・・）

---

以上

不明点があれば遠慮なく。

[KaKkouo]

お知らせ

パッケージのバージョンが変わりましたのでご注意ください。

• sphinxcontrib.kana-text 0.31.4
• sphindexer 0.12.0.1

Sphinx4.4.0でGlossaryクラスから並び替え処理がGlossarySorterに分割されていると思いますが、
この変更への追従になります。

---

kana_text補足

PyPIサイトのkana_textページを見るとcircleciがfailになっていますが、
これはsphindexerの最新版がcircleci環境で使われていないためです。

circleciの設定がよくわかっていないので対応に時間がかかりますが、
それぞれ最新版を使えば問題ないので、すいませんが気にしないでください。

直しました。

以前アドバイスしていただいて直したはずの、setup.py, setup.cfgの内容が
修正前の内容になっていたため、これについて対処しました。

---

sphindexer補足

同じPyPIサイトのsphindexerページを見るとカバレッジがアレですが、
ファイル構成の都合なので、これもすいませんが無視してください。

サイトにアクセスして詳細を見れば、事情の一端が分かります。

---

その他

同じコメントを結構頻繁に更新しています。
何度もメールが送信されていたらごめんなさい。

[KaKkouo]

お知らせ

パッケージを更新しました。

• sphinxcontrib.kana-text 0.32.1
• sphindexer 0.12.2

読み情報の優先順（辞書ファイル、インライン）の整理、ルビ表示の指定方法の変更なので、
現状のPR（辞書ファイル使用、ルビ表示なし）には影響ありません。

あと辞書ファイルですが、rstファイルに対応したhtmlでのルビ表示においては辞書ファイルの内容は反映されません。
前の前のコメントではこの点についても辞書ファイルの内容が反映されるつもりで書いていました。すいません。

たたき台

Sphinx本体の他のissueやPRがあり、ボリュームのある本件はなかなか手を出し辛い内容だと思います。
私なりに「こんな流れになるだろうなぁ」と思っている内容を書き出しておくので、参考にしてください。
（このたたき台がきっかけで、たたき台とは丸々違った展開になるのもアリだと思います）
（また「現状は見送り」であるなら、ショックはショックですが説明していただければ受け入れます）

たたき台を書き出した後での私なりの感触としては、

• sphinx本体としては、indexrack.pyの内容を評価して、変更が必要な点は変更して採用
• shipnx-user.jpとしては、記法で重心する点や実際の記法を整理して、kana_textの扱いを決定
  • 私としては採用してもらったほうが嬉しいのは勿論ですが、「場合によってはkana_textの採用は見送りもあるかなぁ、、、」と思っています。
  • 作る側の我が侭を言わせていただくと、他の記法を希望されるにしても、先ずkana_textを使っていただいて具体的な要望にしてもらえるとモチベーションが充填されるので嬉しいです。この「具体的な要望」についてはsphinx-user.jpのサイトである必要はありません。

①大きな方針として

先ず次の大枠についてどう思っているのかが気になります。

Sphinx本体側として

• sphindexerとkana_textの機能分担と、sphindexerの役割

sphinx-users.jpとして

• 記法の方針、記法の決定、kana_textの採用方針（不採用、暫定採用、恒久採用）

前の前のコメントに書いた「提案的な要点」に対して、取り敢えず「断定はできないけど、
良さそうに思える。良さそうな気がする」であれば、以降の内容へ。

②Sphinx本体として

（厳密に言えばkana_textの範疇からは外れますが、日本語で書くと楽なのでここに書きます）

現在PRしているindexrack.pyの評価を進めることになると思います。

• 方針通りの機能分担になっているか
• 拡張性について

取り敢えず「2.2. ソースコードの読み方」を読んでみて、
印象を教えていただければ此方の対応もイメージしやすいような気がします。
（質問があればissueを起こしてください。StackOverflowでも）

ーーー取り敢えずは、ここまでが第一段階だと思いますーーー

現在のPRの要点は次の通りです

• glossaryで「：」で分類子を使った時に、「make clean」からしないと索引ページが崩れる問題の解消
• 異なるファイルに存在する同名関数の表示で、1つ目の表示が常に「複数表示ではない」表示になっている振る舞いの解消
• 「see/seealso」について、singe/parir/tripleの中に紛れないように表示
• 拡張性。
  • 拡張性の肝は「textclass, packclass, entryclass, unitclass」というクラス変数を介して他のクラスを使っている点ですが、この機構その他のためにスクラッチからindexrack.pｙを作っています。
    • スクラッチから作っているせいで評価作業の敷居が高くなっているのだろうと想像しています(^^;
    • indexentries.pyは段階的且つ局所的に並び替えをやっているので、 全体を見て一括で並び替えるindexrack.sort_unitsの方がやり方としてはいいような気がします。

上記4点の確認

• 「make clean」をしないと崩れる件について、rstファイルベースでの再現ケースが必要なら教えてください。テストケースとしてはPRに含まれています。
• 「異なるファイルに存在する同名関数」はテストケースベースになりますが、PRに含まれています。rstファイルベースでの「異なるファイルに存在する同名関数」のサンプルの作り方を教えていただければ、rstファイルでの再現ケースも作れると思います。
• 拡張性については、kana_text側が一例となります。

今後PRする予定の機能も含まれていますが、sphindexerパッケージを入れれば挙動の違いが確認できます。
機能改善版は「make idxr」で、現状維持版は「make html」でビルドされます。

③sphinx-users.jpとして

「索引での表示」「ルビ表示」のどちらを重視するかが要点になります。
（個人的には「索引での表示を重視」をお薦めしますが…）

流れとしては次のような感じでしょうか

1. 「索引での表示」「ルビ表示」のどちらを重視するか整理する
2. これを踏まえてsphinx-users.jpとして望ましい記法を（仮ぎめだとしても）決める
3. kana_textについての方針（不採用、暫定採用、採用）を決める。

以前記法については、こちらの「<読み情報を付与する記法について>」にまとめています。
https://ja.stackoverflow.com/questions/83053/

ここを見れば「なろう」「カクヨム」その他の記法が確認できますので、
先ずはkana_textで採用している記法と「なろう」「カクヨム」で採用している記法を比較考察すれば、
sphinx-users.jpとしての方針が固まるような気がします。

記法について

• kana_textは「よみ|文字^ルビ表示の詳細指定」となります。
• 「なろう」「カクヨム」は「|文字《よみ》」を読みの指定が必要な箇所毎に記述します。

索引での表示順を重視するなら読み情報は3文字で十分だと思います。

1. 「用語」を例にすれば、「用」ではなく「よ」「や」と表示されればOK⇒1文字目
2. 同じ「よ」「や」の中での表示順が崩れないようにしたい⇒2文字目
3. 念の為⇒3文字目

ルビ表示を重視するなら「なろう」「カクヨム」の記法を採用するのがいいと思います。

• 読みの指定が複数箇所に存在することになるため、kana_textの記法とはまた違う記法の解析方法を組むことになります。
• この記法を採用した場合、「索引ページの表示順が解消されればいい」という理由で先頭の3文字だけを指定する場合のために、「ルビ表示をする/しない」の個別の指定が必要な気がします。（「個別の指定をしない」をいう選択もあるかもしれません）

kana_textを作った者としてはこの記法から見えているものが多いため、結果的に偏った内容になっていると思います。
この点に留意してください。

以上

この内容に限らず不明点はお気軽に。