System requirements¶

Tested with 32bit version of Python 2.7.10 and 64bit version of 3.4.3, both on the Microsoft Windows 8.1 Pro 64bit edition. But with another versions and on another OSs would be usable.

Python 3 is required if you need full unicode support. When used with Python 2, the usable character set is limited with local encoding.

How to install¶

You can install this package as you will do with another one.

1. Open a console and do pip install gosyu.

   On the MS-Windows, <python_installed_path>\Scripts\pip.exe install gosyu.

2. Or when you get zip archive like gosyu-2.0.5(.zip) where ‘2.0.5’ is version number, change current directiory to the folder that has the zip file, and do pip install gosyu-2.0.5.zip.

   On the MS-Windows, <python_installed_path>\Scripts\pip.exe install gosyu-2.0.5.zip.

3. Or, this way is the Sphinx specific, you can use this package just extracted any folder you want. the conf.py enables you to use the themes and extensions.

If you don’t resolve dependencies, you also have to get sortorder module.

1) Add the paths¶

As another extensions, you can use this extension by editing conf.py.

First, you should add:

# add 4 lines below
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'))

Or, when you don’t install with pip or like,

# add just 2 line below
sys.path.insert(0, '<path_to_the_folder_contains_sortorder___init___py>')
sys.path.insert(0, '<path_to_the_folder_contains_gosyu_py>')

If you want to use your own sort order module(.py file), you should add the path of it, too:

# after adding paths as above, add the line below.
sys.path.insert(0, '<path_to_the_folder_sort_order_xx_py>')

2) declare the extensions¶

Next, add gosyu extension into extension list:

language = 'xx' # make sure your language if you want to use autodetect

#
# (snip...)
#

extension = [
  'sort_order_xx', # omit when using one of preset sort order or autodetect
  'sortorder', # you can omit always, because 'gosyu' automatically loads
  'gosyu', # required.
] # Of course you can add another extensions.

3) replace ‘glossary’ with ‘gosyu’¶

Now, just replace .. glossary:: with .. gosyu::. When :sorted: is given, the terms are sorted in each glossary.

And anyway, the general index in genindex.html is also sorted as you want to define.

4) add the how to read each terms¶

For the languages like Japanese, .. gosyu:: directive has another option :yomimark: <a separater char>. the separator is a character you want to use split. When the separator is given, the term can be followed the string how to read. If you think some terms don’t need the reading, you can simply omit for the terms.

Consider to use the preset Japanese sort order defined in sortorder extension:

language = 'ja'

#
# (snip...)
#

extension = [
  'gosyu',
]  # all omitted modules will be automatically loaded

And write glossary like:

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

  ひらがな

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

  カタカナ

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

  漢字、かんじ

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

  英字、えいじ

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

  記号、きごう

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

The separator is 、 (U+3001) in this case.

This reorders the terms 英字 -> カタカナ -> 漢字 -> 記号 -> ひらがな. The preset sortorder.ja module sorts them depending on えいじ, カタカナ, かんじ, きごう, ひらがな.

And in the genindex.html, カタカナ, 漢字, 記号 is grouped in one heading か. Also because the module desides it depending on how to read.

5) options written in conf.py¶

There is 3 options to change some strings.

• gosyu_shortname = u'用語集'
  • a short name for the index, for use in the relation bar in
• gosyu_localname = u'用語集'
  • the section title for the index
• gosyu_anchor_prefix = 'yogo_'
  • the prefix of the anchors to link from/to HTML files.