diff options
Diffstat (limited to 'docs/_ext/autosectionlabel.py')
| -rw-r--r-- | docs/_ext/autosectionlabel.py | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/docs/_ext/autosectionlabel.py b/docs/_ext/autosectionlabel.py new file mode 100644 index 00000000..aea59fac --- /dev/null +++ b/docs/_ext/autosectionlabel.py @@ -0,0 +1,71 @@ +""" + sphinx.ext.autosectionlabel + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Allow reference sections by :ref: role using its title. + :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from typing import Any, Dict, cast + +from docutils import nodes +from docutils.nodes import Node + +from sphinx.application import Sphinx +from sphinx.domains.std import StandardDomain +from sphinx.locale import __ +from sphinx.util import logging +from sphinx.util.nodes import clean_astext + +logger = logging.getLogger(__name__) + + +def get_node_depth(node: Node) -> int: + i = 0 + cur_node = node + while cur_node.parent != node.document: + cur_node = cur_node.parent + i += 1 + return i + + +def register_sections_as_label(app: Sphinx, document: Node) -> None: + domain = cast(StandardDomain, app.env.get_domain('std')) + for node in document.traverse(nodes.section): + if (app.config.autosectionlabel_maxdepth and + get_node_depth(node) >= app.config.autosectionlabel_maxdepth): + continue + labelid = node['ids'][0] + docname = app.env.docname + title = cast(nodes.title, node[0]) + ref_name = getattr(title, 'rawsource', title.astext()) + if app.config.autosectionlabel_prefix_document: + name = nodes.fully_normalize_name(docname + ':' + ref_name) + else: + name = nodes.fully_normalize_name(ref_name) + sectname = clean_astext(title) + + if name in domain.labels: + # a ref befor a headline create 2 ids in the node object + if len(node['ids']) > 1: + continue + logger.warning(__('duplicate label %s, other instance in %s'), + name, app.env.doc2path(domain.labels[name][0]), + location=node, type='autosectionlabel', subtype=docname) + + + + domain.anonlabels[name] = docname, labelid + domain.labels[name] = docname, labelid, sectname + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.add_config_value('autosectionlabel_prefix_document', False, 'env') + app.add_config_value('autosectionlabel_maxdepth', None, 'env') + app.connect('doctree-read', register_sections_as_label) + + return { + 'version': 'builtin', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + }
\ No newline at end of file |