Generally, you don’t have to know read here. Please read sortorder extension.

通常はこの頁を読む必要はありません。使い方などについてはsortorder拡張(日本語版説明書)をご覧ください。

sortorder.__init__.py

The Sphinx extension to provide sort order.

copyright:© 2011-2015 by Suzumizaki-Kimitaka(鈴見咲君高)
license:2-clause BSD

You can define sort_order_LANG.py to give new order for indices to replace the default order.

Any sort_order_LANG.py should have the method get_default_sort_order() The method should return the object which inherits SortOrderBase.

class sortorder.SortOrderBase

Base class of any SortOrder-s

Any sort order classes should inherit this class. You can refer sortorder/xx.py as the sample implementation. You may want to inherit SortOrderLegacy or SortOrderLegacyLike instead of this class.

get_group_name(entry_name)

Return the group name of the given entry

Parameters:entry_name (str_or_unicode) – the name of the entry
Return type:str(Python 3), unicode(Python 2)
Returns:the name of the group which the given name belongs to

Grouping itself should be done by get_string_to_sort() function. See the implementation of SortOrderLegacy.

get_string_to_sort(entry_name)

Return the string for sorting instead of given name

Parameters:entry_name (str_or_unicode) – the name of the entry
Return type:str(Python 3), unicode(Python 2)
Returns:the internal sort key, should be sortable each other

All inheriting class may override this function.

Return the internal sort key refering the given name.

The internal sort key should be sortable with the unicode codepoint order. For example, when your indices have the group “Etc.” or “Symbols”, the return value from this function should have the group marker character prefix against such entries.

Like above, when unfortunately your grouping cannot unify single range of the unicode codepoint, the return value also should have prefix.

You can just return the entry_name if you don’t have to give internal sort key.

Check the implementation of SortOrderLegacy. You may want to inherit that class to ignore cases or so.

class sortorder.SortOrderLegacy

Perform sort order given like Sphinx 1.0.7 or prior

get_group_name(entry_name)

Return the group name of the given entry

This class/function gives just only English specific sort order. The alphabet is limited only in ascii and force all characters NFD normalization.

get_string_to_sort(entry_name)

Return the string for sorting instead of given name

To make the grouping done, making lowercased, ‘NFD’ normalization and prepend prefix to symbols.

class sortorder.SortOrderLegacyLike

Base class for lauguages similar to latin.

etc_form()

Return the word ‘etc.’ in your language

Override this.

get_group_name(entry_name)

Return the group name of the given entry

get_string_to_sort(entry_name)

Return the string to sort

get_uppercases()

Return uppercased characters used in your language

Override this.

sortorder.get_default_sort_order(cfg)

Return the default sort order of the language given in conf.py

Parameters:cfg (sphinx.config.Config) – you can give from Sphinx with app.config, builder.config etc.
Return type:SortOrderBase
Returns:the object of the class inherits SortOrderBase.
Seealso:get_sort_order()

Indend to be called by another extensions.

sortorder.get_sort_order(cfg)

Return SortOrderBase object depends on given Sphinx configure

Parameters:cfg (sphinx.config.Config) – you can give from Sphinx with app.config, builder.config etc.
Return type:SortOrderBase
Returns:the object of the class inherits SortOrderBase.

Convenient function of get_default_sort_order(). Indend to be called by another extensions.

When cfg.sort_order has SortOrderBase, just return it. Otherwise, return get_default_sort_order().

sortorder.setup(app)

Placeholder method called by the Sphinx document generator

Parameters:app (sphinx.application.Sphinx) – the object to extend the Sphinx

Just place holder. do nothing.