from __future__ import absolute_import """Sphinx Bulma theme. Based on https://github.com/rtfd/sphinx_rtd_theme """ from docutils.nodes import Admonition from docutils.nodes import attention from docutils.nodes import caution from docutils.nodes import danger from docutils.nodes import error from docutils.nodes import hint from docutils.nodes import important from docutils.nodes import note from docutils.nodes import tip from docutils.nodes import title from docutils.nodes import warning from sphinx.addnodes import seealso from six import string_types from .fs import module_path from .version import version """ maps :py:class:`docutils.nodes.Admonition` subclasses to `bulma message color classes <https://bulma.io/documentation/components/message/#colors>`_ """ admonition_map = { seealso: 'is-success', tip: 'is-primary', note: 'is-warning', warning: 'is-danger', attention: 'is-warning', caution: 'is-warning', danger: 'is-danger', error: 'is-danger', hint: 'is-info', important: 'is-link', } [docs]def get_html_theme_path(): """For use inside Sphinx's ``conf.py`` file: .. code:: python import sphinx_bulma_theme html_theme = "bulma" html_theme_path = [sphinx_bulma_theme.get_html_theme_path()] html_theme_options = { 'show_topbar': False, 'sidebar_right': True, } """ return str(module_path) [docs]def add_classes_to_node(class_names, node): """sets a list of class names in the node. Used for injecting `bulma modifiers <https://bulma.io/documentation/modifiers/color-helpers/>`_ in the final HTML generated by Sphinx. :param class_names: a list of strings :param node: the target node """ if isinstance(class_names, string_types): class_names = class_names.split() return list(map(node.set_class, class_names)) [docs]def process_admonition_node(node, admonition_type, color, size): """applies the given color and size modifiers to admonition nodes :param node: the target :py:class:`docutils.nodes.Admonition` (subclass) node :param admonition_type: see :py:data:`sphinx_bulma_theme.admonition_map` :param color: a string, such as ``is-danger`` :param size: a string, such as ``is-small`` or **None** """ add_classes_to_node(['message', size, color], node) for child in node.traverse(title): add_classes_to_node('message-header', child) # for child in node.traverse(admonition_type): # add_classes_to_node('message-body', child) # break [docs]def bulmanize_documentation(app, doctree, fromdocname): """applies necessary internal node transformations before HTML rendering: - Loads the ``admonition_class`` from :ref:`theme options` - Iterate over :py:data:`sphinx_bulma_theme.admonition_map` """ theme_options = app.config.html_theme_options message_size = theme_options.get('default_admonition_class', '') # size = app.env.conf.get('') # nodes = list(filter(lambda n: 'also' in str(n).lower(), doctree.traverse(Element))) # for node in nodes: # print(node) # import ipdb; ipdb.set_trace() # atts = dict(node.attlist()) # names = " ".join(atts.get('names') or []) # for ad_type, color in admonition_map.items(): # ad_name = ad_type.__name__ # if ad_name in names: # process_admonition_node(node, ad_type, color) for node in doctree.traverse(Admonition): message_color = admonition_map.get(node.__class__, 'is-dark') process_admonition_node(node, node.__class__, message_color, message_size) # def handle_page_context(app, pagename, templatename, context, doctree): # pass def setup(app): app.add_html_theme('bulma', get_html_theme_path()) app.connect('doctree-resolved', bulmanize_documentation) # app.connect('html-page-context', handle_page_context) __all__ = ( 'get_html_theme_path', 'version', 'setup', 'admonition_map', )