# -*- coding: utf-8 -*-
"""
Defines a :epkg:`sphinx` extension to keep track of nb.
:githublink:`%|py|6`
"""
from docutils import nodes
import sphinx
from .sphinx_blocref_extension import BlocRef, process_blocrefs_generic, BlocRefList, process_blocref_nodes_generic
[docs]class nbref_node(nodes.admonition):
"""
defines ``nbref`` ndoe
:githublink:`%|py|15`
"""
pass
[docs]class nbreflist(nodes.General, nodes.Element):
"""
defines ``nbreflist`` node
:githublink:`%|py|22`
"""
pass
[docs]class NbRef(BlocRef):
"""
A ``nbref`` entry, displayed in the form of an admonition.
It takes the following options:
* *title*: a title for the bloc
* *tag*: a tag to have several categories of blocs, if not specified, it will be equal to *nb*
* *lid* or *label*: a label to refer to
* *index*: to add an additional entry to the index (comma separated)
See :ref:`%encrypt_file <l-nb-encrypt-file>` for an example.
All entries can be aggregated per tag with ``nbreflist``::
.. nbreflist::
:tag: dummy_example2
:sort: title
It works the same way as :class:`BlocRef <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef>`.
:githublink:`%|py|44`
"""
node_class = nbref_node
name_sphinx = "nbref"
[docs] def run(self):
"""
calls run from :class:`BlocRef <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRef>` and add index entries by default
:githublink:`%|py|52`
"""
if 'title' not in self.options:
lineno = self.lineno
env = self.state.document.settings.env if hasattr(
self.state.document.settings, "env") else None
docname = None if env is None else env.docname
raise KeyError("unable to find 'title' in node {0}\n File \"{1}\", line {2}\nkeys: {3}".format(
str(self.__class__), docname, lineno, list(self.options.keys())))
title = self.options['title']
if "tag" not in self.options:
self.options["tag"] = "nb"
if "index" not in self.options:
self.options["index"] = title
else:
self.options["index"] += "," + title
return BlocRef.run(self)
[docs]def process_nbrefs(app, doctree):
"""
Collect all *nbref* in the environment
this is not done in the directive itself because it some transformations
must have already been run, e.g. substitutions.
:githublink:`%|py|75`
"""
process_blocrefs_generic(
app, doctree, bloc_name="nbref", class_node=nbref_node)
[docs]class NbRefList(BlocRefList):
"""
A list of all *nbref* entries, for a specific tag.
* tag: a tag to have several categories of nbref
* contents: add a bullet list with links to added blocs
Example::
.. nbreflist::
:tag: issue
:githublink:`%|py|91`
"""
name_sphinx = "nbreflist"
node_class = nbreflist
[docs] def run(self):
"""
calls run from :class:`BlocRefList <pyquickhelper.sphinxext.sphinx_blocref_extension.BlocRefList>` and add default tag if not present
:githublink:`%|py|98`
"""
if "tag" not in self.options:
self.options["tag"] = "nb"
return BlocRefList.run(self)
[docs]def process_nbref_nodes(app, doctree, fromdocname):
"""
process_nbref_nodes
:githublink:`%|py|107`
"""
process_blocref_nodes_generic(app, doctree, fromdocname, class_name='nbref',
entry_name="nbmes", class_node=nbref_node,
class_node_list=nbreflist)
[docs]def purge_nbrefs(app, env, docname):
"""
purge_nbrefs
:githublink:`%|py|116`
"""
if not hasattr(env, 'nbref_all_nbrefs'):
return
env.nbref_all_nbrefs = [nbref for nbref in env.nbref_all_nbrefs
if nbref['docname'] != docname]
[docs]def merge_nbref(app, env, docnames, other):
"""
merge_nbref
:githublink:`%|py|126`
"""
if not hasattr(other, 'nbref_all_nbrefs'):
return
if not hasattr(env, 'nbref_all_nbrefs'):
env.nbref_all_nbrefs = []
env.nbref_all_nbrefs.extend(other.nbref_all_nbrefs)
[docs]def visit_nbref_node(self, node):
"""
visit_nbref_node
:githublink:`%|py|137`
"""
self.visit_admonition(node)
[docs]def depart_nbref_node(self, node):
"""
*depart_nbref_node*,
see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_.
:githublink:`%|py|145`
"""
self.depart_admonition(node)
[docs]def visit_nbreflist_node(self, node):
"""
*visit_nbreflist_node*,
see `sphinx/writers/html.py <https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py>`_.
:githublink:`%|py|153`
"""
self.visit_admonition(node)
[docs]def depart_nbreflist_node(self, node):
"""
depart_nbref_node
:githublink:`%|py|160`
"""
self.depart_admonition(node)
[docs]def setup(app):
"""
setup for ``nbref`` (sphinx)
:githublink:`%|py|167`
"""
if hasattr(app, "add_mapping"):
app.add_mapping('nbref', nbref_node)
app.add_mapping('nbreflist', nbreflist)
app.add_config_value('nbref_include_nbrefs', True, 'html')
app.add_config_value('nbref_link_only', False, 'html')
app.add_node(nbreflist,
html=(visit_nbreflist_node, depart_nbreflist_node),
epub=(visit_nbreflist_node, depart_nbreflist_node),
elatex=(visit_nbreflist_node, depart_nbreflist_node),
latex=(visit_nbreflist_node, depart_nbreflist_node),
text=(visit_nbreflist_node, depart_nbreflist_node),
md=(visit_nbreflist_node, depart_nbreflist_node),
rst=(visit_nbreflist_node, depart_nbreflist_node))
app.add_node(nbref_node,
html=(visit_nbref_node, depart_nbref_node),
epub=(visit_nbref_node, depart_nbref_node),
elatex=(visit_nbref_node, depart_nbref_node),
latex=(visit_nbref_node, depart_nbref_node),
text=(visit_nbref_node, depart_nbref_node),
md=(visit_nbref_node, depart_nbref_node),
rst=(visit_nbref_node, depart_nbref_node))
app.add_directive('nbref', NbRef)
app.add_directive('nbreflist', NbRefList)
app.connect('doctree-read', process_nbrefs)
app.connect('doctree-resolved', process_nbref_nodes)
app.connect('env-purge-doc', purge_nbrefs)
app.connect('env-merge-info', merge_nbref)
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
