Register a Docutils node class. This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents. :param node: A node class :param kwargs: Visitor functions for each builder (see below) :param override: I
(
self,
node: type[Element],
override: bool = False,
**kwargs: _NodeHandlerPair,
)
| 973 | self.registry.add_translator(name, translator_class, override=override) |
| 974 | |
| 975 | def add_node( |
| 976 | self, |
| 977 | node: type[Element], |
| 978 | override: bool = False, |
| 979 | **kwargs: _NodeHandlerPair, |
| 980 | ) -> None: |
| 981 | """Register a Docutils node class. |
| 982 | |
| 983 | This is necessary for Docutils internals. It may also be used in the |
| 984 | future to validate nodes in the parsed documents. |
| 985 | |
| 986 | :param node: A node class |
| 987 | :param kwargs: Visitor functions for each builder (see below) |
| 988 | :param override: If true, install the node forcedly even if another node is already |
| 989 | installed as the same name |
| 990 | |
| 991 | Node visitor functions for the Sphinx HTML, LaTeX, text and manpage |
| 992 | writers can be given as keyword arguments: the keyword should be one or |
| 993 | more of ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'`` |
| 994 | or any other supported translators, the value a 2-tuple of ``(visit, |
| 995 | depart)`` methods. ``depart`` can be ``None`` if the ``visit`` |
| 996 | function raises :exc:`docutils.nodes.SkipNode`. Example: |
| 997 | |
| 998 | .. code-block:: python |
| 999 | |
| 1000 | class math(docutils.nodes.Element): ... |
| 1001 | |
| 1002 | def visit_math_html(self, node): |
| 1003 | self.body.append(self.starttag(node, 'math')) |
| 1004 | |
| 1005 | def depart_math_html(self, node): |
| 1006 | self.body.append('</math>') |
| 1007 | |
| 1008 | app.add_node(math, html=(visit_math_html, depart_math_html)) |
| 1009 | |
| 1010 | Obviously, translators for which you don't specify visitor methods will |
| 1011 | choke on the node when encountered in a document to translate. |
| 1012 | |
| 1013 | .. versionchanged:: 0.5 |
| 1014 | Added the support for keyword arguments giving visit functions. |
| 1015 | """ |
| 1016 | logger.debug('[app] adding node: %r', (node, kwargs)) |
| 1017 | if not override and docutils.is_node_registered(node): |
| 1018 | logger.warning( |
| 1019 | __( |
| 1020 | 'node class %r is already registered, ' |
| 1021 | 'its visitors will be overridden' |
| 1022 | ), |
| 1023 | node.__name__, |
| 1024 | type='app', |
| 1025 | subtype='add_node', |
| 1026 | ) |
| 1027 | docutils.register_node(node) |
| 1028 | self.registry.add_translation_handlers(node, **kwargs) |
| 1029 | |
| 1030 | def add_enumerable_node( |
| 1031 | self, |