Module document

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


Module sphinxcontrib.unicode_ids

The Sphinx extension to allow HTML builder to use Non-ASCII identifiers

copyright:© 2011-2015 Suzumizaki-Kimitaka(鈴見咲 君高, for additional works only)
license:2-clause BSD.

This module hacks sphinx.environment.BuildEnvironment.resolve_toctree(). And because of this, when used with Python 2(means not Python 3), just cover characters included in the set of sys.getdefaultencoding(), not all of Unicode characters.

For Windows, you might create or to call sys.setdefaultencoding('mbcs'). See PEP 370 to know where to place the script.


Return identifier without losing Unicode characters.

Parameters:s (str_or_unicode) – base string to make new identifier
Return type:unicode(Python 2), str(Python 3)
Returns:the new identifier string for patched Sphinx

Defined to replace the function docutils.nodes.make_id().

Currently, this function can’t determine the return value will be used in HTML or CSS. Unusable characters will be replaced with _xhh form where hh is 2-digit hexadecimal lowercase.


Show non existing entries of toctree

Parameters:self (sphinx.directives.other.TocTree) – The instance object
Return type:list
Returns:list of the nodes made in this method

Defined to replace the method

Only %r following are replaced with %s to avoid unreadable string.


Extend the Sphinx as we want, called from the Sphinx

Parameters:app (sphinx.application.Sphinx) – the object to add builder or something.

Get unicode object by decoding given string with filesystem encoding

Parameters:s (str) – the string, if unicode object is given, return this unmodified.
Return type:unicode
Returns:the string converted unicode type

When the system encoding is not found, just return the parameter s. This function is called Python 2 only.