Source code for pyquickhelper.sphinxext.sphinx_ext_helper

"""
Few helpers for :epkg:`Sphinx`.


:githublink:`%|py|5`
"""
import logging


[docs]def info_blocref(app, doctree, fromdocname, class_name, entry_name, class_node, class_node_list): """ Log information with :epkg:`Sphinx`. :param app: application (Sphinx) :param doctree: document tree :param fromdocname: document currently being compiled :param class_name: name of the node :param entry_name: entry name in ``TITLES`` :param class_node: class node (:class:`blocref_node <pyquickhelper.sphinxext.sphinx_blocref_extension.blocref_node>`) :param class_node_list: class node list (:class:`blocreflist <pyquickhelper.sphinxext.sphinx_blocref_extension.blocreflist>`) :githublink:`%|py|20` """ incconf = '%s_include_%ss' % (class_name, class_name) rows2 = [] for node in doctree.traverse(class_node_list): breftag = node.get("breftag", None) rows2.append("tag={0} do={1}".format(breftag, app.config[incconf])) if len(rows2) == 0: return False attr_name = '%s_all_%ss' % (class_name, class_name) env = app.builder.env if hasattr(env, attr_name): bloc_list_env = getattr(env, attr_name) else: bloc_list_env = [] rows = [" [info_blocref]", "len(bloc_list_env)={0}".format(len(bloc_list_env)), ] rows.extend(rows2) rows.extend(["fromdocname='{0}'".format(fromdocname), "entry_name='{0}'".format(entry_name), "class_name='{0}'".format(class_name), "class_node='{0}'".format(class_node), "class_node_list='{0}'".format(class_node_list), "doctree='{0}'".format(type(doctree)), "#doctree={0}".format(len(doctree))]) message = " ".join(rows) logger = logging.getLogger("info_blocref") logger.info(message) return True
[docs]def sphinx_lang(env, default_value='en'): """ Returns the language defined in the configuration file. :param env: environment :param default_value: default value :return: language :githublink:`%|py|59` """ if hasattr(env, "settings"): settings = env.settings if hasattr(settings, "language_code"): lang = env.settings.language_code else: lang = "en" else: settings = None lang = "en" return lang
[docs]class TinyNode: """ Returned by :func:`traverse <pyquickhelper.sphinxext.sphinx_ext_helper.traverse>`. :githublink:`%|py|75` """
[docs] def __init__(self, parent): """ Create a note :param parent: parent node :githublink:`%|py|82` """ self.parent = parent
[docs]class NodeEnter(TinyNode): """ Returned by function :func:`traverse <pyquickhelper.sphinxext.sphinx_ext_helper.traverse>`. :githublink:`%|py|89` """ pass
[docs]class NodeLeave(TinyNode): """ Returned by function :func:`traverse <pyquickhelper.sphinxext.sphinx_ext_helper.traverse>`. :githublink:`%|py|96` """ pass
[docs]class WrappedNode: """ Wraps a docutils node. :githublink:`%|py|103` """
[docs] def __init__(self, node): self.node = node
[docs]def traverse(node, depth=0): """ Enumerates through all children but insert a node whenever digging or leaving the childrens nodes. :param node: node (from doctree) :param depth: current depth :return: enumerate (depth, node) :class:`NodeEnter <pyquickhelper.sphinxext.sphinx_ext_helper.NodeEnter>` and :class:`NodeLeave` are returned whenever entering or leaving nodes. :githublink:`%|py|119` """ if isinstance(node, WrappedNode): node = node.node ne = NodeEnter(node) nl = NodeLeave(node) yield (depth, ne) yield (depth, node) for n in node.children: for r in traverse(n, depth + 1): yield r yield (depth, nl)