動作条件¶

32ビット版のPython 2.7.10と64ビット版のPython 3.4.3をマイクロソフトウィンドウズ 8.1上で動かして挙動を確認しました。特段の依存性はないので、他のPython実装や他のOSでも動作すると思います。

Unicodeで定義された全文字への対応はPython 3が必須です。Python 2ではその標準符号化法かファイルシステムの符号化法に利用できる文字が限定されます。

設置方法¶

前述の通り、通常のPythonパッケージと同様の方法で設置できます。

1. コンソールを開きpip install gosyuを実行してください。

   マイクロソフトウィンドウズではpythonを設置したフォルダ\Scripts\pip.exe install gosyuを実行してください。

2. あるいはgosyu-2.0.5(.zip)(2.0.5はバージョン番号)というファイルを入手し、このファイルがあるフォルダへ移動した後pip install gosyu-2.0.5.zipを実行してください。

   同様にウィンドウズでは代わりにpythonを設置したフォルダ\Scripts\pip.exe install gosyu-2.0.5.zipを実行してください。

3. 最後の別の方法として、これはSphinx特有の方法ですが、単にzipファイルを任意のフォルダに展開して使うという手段があります。Sphinxで使うconf.pyを適切に編集することで利用可能です。

依存関係を解決しなかった場合は、別途 sortorder が必要となります。

1) パスの追加¶

他のSphinx拡張同様、conf.pyの編集によって使えるようになります。

まず、次のコードを追加してください:

# 次の4行を追加
import distutils.sysconfig
site_package_path = distutils.sysconfig.get_python_lib()
sys.path.insert(0, os.path.join(site_package_path, 'sortorder'))
sys.path.insert(0, os.path.join(site_package_path, 'sphinxcontrib/gosyu'))

ただし、もしpipで設置していないのであれば代わりに次を追加してください:

# 代わりに次の2行を追加
sys.path.insert(0, '<sortorder.__init__.pyがあるフォルダへのパス>')
sys.path.insert(0, '<gosyu.pyがあるフォルダへのパス>')

さらに独自の並び順を提供するPythonファイルがある場合は、それへのパスも追加してください:

# 上記のいずれかに加えて次の行を追加
sys.path.insert(0, '<用意した独自sort_order_xx.pyがあるフォルダへのパス>')

2) 使う拡張の宣言¶

次に当拡張を extension の中で宣言してください:

language = 'xx' # 自動読み込みを使う場合は言語指定を確認して下さい

#
# (中略)
#

extension = [
  'sort_order_xx', # 自動検出かsortorderで提供するものを使う場合は省きます
  'sortorder', # gosyu拡張が自動的に読み込むので省略できます
  'gosyu', # 必須です
] # もちろん他の拡張も任意で追加できます

3) ‘glossary’ を ‘gosyu’ に置き換え¶

ここまでできましたら、.. glossary:: directiveを .. gosyu:: に置き換えるだけです。:sorted: はそのままで使えます。

std-gosyu.html が総合索引とは別に出力され、そちらでは索引としての指定された並び順とグループ化が行われるようになります。

4) 読みがなを加える¶

日本語のような言語で使うために .. gosyu:: directive は :yomimark: <区切り文字> という option も用意しています。:yomimark: で指定した文字の前が本来の用語、後ろが読みがなという形になります。

日本語での使用例を示します。conf.pyで次のように記述してください:

language = 'ja'

#
# (中略)
#

extension = [
  'user_ordered_index_patch',
]  # 省略された拡張は前述のとおりすべて自動的に読み込まれます

その上で次のように用語集を記述した場合を考えます:

.. gosyu::
  :sorted:
  :yomimark: 、

  ひらがな

    比較的曲線が多い日本語の表音文字

  カタカナ

    比較的直線が多い日本語の表音文字

  漢字、かんじ

    日本語でも使われる表意文字

  英字、えいじ

    義務教育で教わるため、日本語でもよく使われる表音文字

  記号、きごう

    国内国外を問わず多種多様な記号が携帯電話などでも使えるようになってきた

ここでは区切り記号を読点 、 (U+3001) にしています。

単語は 英字→カタカナ→漢字→記号→ひらがな の順で並べられます。 sortorder.ja module が読みがなである えいじ, カタカナ, かんじ, きごう, ひらがな にもとに判断するからです。

また genindex.html においては カタカナ, 漢字, 記号 が単一の見出し か にまとめられます。やはり同じ module が指定された読みがなに基いて振り分けを行うからです。

5) conf.py で変更できる設定¶

用語集に関連するいくつかの文字列を変更できます。

• gosyu_shortname = u'用語集'
  • relation bar に表示する用語集へのリンク文字列です。
• gosyu_localname = u'用語集'
  • 用語集のHTMLファイル冒頭に表示する見出し文字列です。
• gosyu_anchor_prefix = 'yogo_'
  • HTMLファイルの中でリンクに使われるanchorの前置部文字列です。