diff options
| -rw-r--r-- | docs/_ext/autosectionlabel.py | 71 | ||||
| -rw-r--r-- | docs/conf.py | 5 | ||||
| -rw-r--r-- | docs/documentation.rst | 53 |
3 files changed, 129 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 diff --git a/docs/conf.py b/docs/conf.py index 594d6063..3e95e52d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -45,12 +45,17 @@ extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.ifconfig', 'sphinx.ext.graphviz', 'notfound.extension', + 'autosectionlabel', 'vyos' ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +# autosectionlabel +autosectionlabel_prefix_document = True + + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # diff --git a/docs/documentation.rst b/docs/documentation.rst index 7b410e95..f869922b 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -137,6 +137,59 @@ We use the following syntax for Headlines. Paragraphs """""""""" +Cross-References +^^^^^^^^^^^^^^^^ + +A plugin will used to generate a reference lable of each headline. +To reference a page or a section in the documentation use the ``:ref:`` +command. + +For example you want to reference the headline **VLAN** in the +**ethernet.rst** page. The plugin generates label based on headline +and the file path. + +``:ref:`configuration/interfaces/ethernet:vlan`` + +to use a alternative Hyperlink use it this way: + +``:ref:`Check out VLAN<configuration/interfaces/ethernet:vlan>`` + +handle build errors +""""""""""""""""""" + +The plugin will warn on build if a headline has a duplicate name in the +same document. To prevent this warning you have to put a custom link on +top of the headline. + +.. code-block:: + + Section A + ========== + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr + + Example + ------- + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr + + Section B + ========== + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr + + .. _section B example: + + Example + ------- + + Lorem ipsum dolor sit amet, consetetur sadipscing elitr + + + + + + Address space ^^^^^^^^^^^^^ |