Merge pull request #546 from rebortg/autosectionlabel

Autosectionlabel

20 files changed, 198 insertions, 1 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/changelog/1.2.6.rst b/docs/changelog/1.2.6.rst
index 8ea92657..70786d07 100644
--- a/docs/changelog/1.2.6.rst
+++ b/docs/changelog/1.2.6.rst
@@ -17,6 +17,8 @@ performance degradation via a specially crafted authoritative DNS server reply.
 
 1.2.6 is a maintenance release made in September 2020.
 
+.. _resovled issues 1.2.6:
+
 Resolved issues
 ---------------
 
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/configexamples/ha.rst b/docs/configexamples/ha.rst
index aa184d09..401d7b9f 100644
--- a/docs/configexamples/ha.rst
+++ b/docs/configexamples/ha.rst
@@ -332,6 +332,8 @@ hardware router.
    set service conntrack-sync mcast-group '224.0.0.50'
    set service conntrack-sync sync-queue-size '8'
 
+.. _ha:contracktesting:
+
 Testing
 -------
 
diff --git a/docs/configexamples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst
index f26f3ce6..cd150121 100644
--- a/docs/configexamples/wan-load-balancing.rst
+++ b/docs/configexamples/wan-load-balancing.rst
@@ -67,6 +67,9 @@ Example 2: Failover based on interface weights
 
 This examples uses the failover mode.
 
+
+.. _wan:example2_overwiew:
+
 Overview
 ^^^^^^^^
 In this example eth0 is the primary interface and eth1 is the secondary
@@ -94,6 +97,8 @@ The previous example used the failover command to send traffic thorugh
 eth1 if eth0 fails. In this example failover functionality is provided
 by rule order.
 
+.. _wan:example3_overwiew:
+
 Overview
 ^^^^^^^^
 Two rules will be created, the first rule directs traffic coming in
@@ -122,6 +127,9 @@ secondary link has a lower speed and should only carry high priority
 traffic. It is assumed for this example that eth1 is connected to a
 slower connection than eth0 and should prioritise VoIP traffic.
 
+
+.. _wan:example4_overwiew:
+
 Overview
 ^^^^^^^^
 A rule order for prioritising traffic is useful in scenarios where the
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst
index 02cfc7d1..667a4653 100644
--- a/docs/configuration/firewall/index.rst
+++ b/docs/configuration/firewall/index.rst
@@ -830,6 +830,8 @@ IPv6
    Use this command to set the maximum segment size for IPv6 transit
    packets on a specific interface (1280-1492 bytes).
 
+.. _firewall:ipv6_example:
+
 Example
 -------
 
diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst
index 8b32743f..a30a0b81 100644
--- a/docs/configuration/interfaces/openvpn.rst
+++ b/docs/configuration/interfaces/openvpn.rst
@@ -481,6 +481,8 @@ and another VyOS router acting as OpenVPN client. The Server also pushes a
 static client IP address to the OpenVPN client. Remember, clients are identified
 using their CN attribute in the SSL certificate.
 
+.. _openvpn:client_server:
+
 Server
 ------
 
@@ -505,6 +507,8 @@ Server
   set interfaces openvpn vtun10 tls key-file '/config/auth/server.key'
   set interfaces openvpn vtun10 use-lzo-compression
 
+.. _openvpn:client_client:
+
 Client
 ------
 
diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst
index f1f15f38..25ec3038 100644
--- a/docs/configuration/protocols/bgp.rst
+++ b/docs/configuration/protocols/bgp.rst
@@ -222,6 +222,7 @@ Defining Peers
    Specify the IPv4 source address to use for the BGP session to this neighbor,
    may be specified as either an IPv4 address directly or as an interface name.
 
+.. _bgp_capability_negotiation:
 
 Capability Negotiation
 ^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/configuration/protocols/igmp.rst b/docs/configuration/protocols/igmp.rst
index 7109deb6..233e9828 100644
--- a/docs/configuration/protocols/igmp.rst
+++ b/docs/configuration/protocols/igmp.rst
@@ -225,6 +225,8 @@ Configuration
 
    Disable this service.
 
+.. _igmp:proxy_example:
+
 Example
 -------
 
diff --git a/docs/configuration/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst
index 76727517..64d7a893 100644
--- a/docs/configuration/protocols/ospf.rst
+++ b/docs/configuration/protocols/ospf.rst
@@ -743,9 +743,13 @@ address and the node 1 sending the default route:
 OSPFv3 (IPv6)
 *************
 
+.. _ospf:v3_configuration:
+
 Configuration
 =============
 
+.. _ospf:v3_general:
+
 General
 -------
 
@@ -768,6 +772,8 @@ process starts when the first ospf enabled interface is configured.
    configured with the same router-ID!
 
 
+.. _ospf:v3_optional:
+
 Optional
 --------
 
@@ -783,6 +789,7 @@ Optional
    distance values for external routes, inter-area routes and intra-area
    routes respectively. The distance range is 1 to 255.
 
+.. _ospf:v3_area_configuration:
 
 Area Configuration
 ------------------
@@ -799,6 +806,7 @@ Area Configuration
    intra area paths from this range are not advertised into other areas. This
    command makes sense in ABR only.
 
+.. _ospf:v3_interface_config:
 
 Interface Configuration
 -----------------------
@@ -869,6 +877,7 @@ Interface Configuration
    synchronizing process of the router's database with all neighbors. The
    default value is 1 seconds. The interval range is 3 to 65535.
 
+.. _ospf:v3_redistribution_config:
 
 Redistribution Configuration
 ----------------------------
@@ -885,6 +894,7 @@ Redistribution Configuration
    given route source. There are five modes available for route source: bgp,
    connected, kernel, ripng, static.
 
+.. _ospf:v3_op_cmd:
 
 Operational Mode Commands
 -------------------------
@@ -932,6 +942,7 @@ Operational Mode Commands
 
    This command displays external information redistributed into OSPFv3
 
+.. _ospf:v3_config_example:
 
 Configuration Example
 ---------------------
diff --git a/docs/configuration/service/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst
index 5355a0fd..c0394dff 100644
--- a/docs/configuration/service/dhcp-relay.rst
+++ b/docs/configuration/service/dhcp-relay.rst
@@ -99,6 +99,8 @@ Operation
 IPv6 relay
 **********
 
+.. _dhcp-relay:ipv6_configuration:
+
 Configuration
 =============
 
@@ -114,6 +116,8 @@ Configuration
    Specifies an upstream network `<interface>` from which replies from
    `<server>` and other relay agents will be accepted.
 
+.. _dhcp-relay:ipv6_options:
+
 Options
 -------
 
@@ -126,6 +130,8 @@ Options
    If this is set the relay agent will insert the interface ID. This option is
    set automatically if more than one listening interfaces are in use.
 
+.. _dhcp-relay:ipv6_example:
+
 Example
 =======
 
@@ -151,6 +157,8 @@ The generated configuration will look like:
          address 2001:db8::4
       }
 
+.. _dhcp-relay:ipv6_op_cmd:
+
 Operation
 =========
 
diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst
index 3f435605..a6f64aa4 100644
--- a/docs/configuration/service/dhcp-server.rst
+++ b/docs/configuration/service/dhcp-server.rst
@@ -317,6 +317,8 @@ Example
 
 Please see the :ref:`dhcp-dns-quick-start` configuration.
 
+.. _dhcp-server:v4_example_failover:
+
 Failover
 --------
 
@@ -357,6 +359,7 @@ Common configuration, valid for both primary and secondary node.
   set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover peer-address '192.168.189.252'
   set service dhcp-server shared-network-name NET-VYOS subnet 192.0.2.0/24 failover status 'primary'
 
+.. _dhcp-server:v4_example_raw:
 
 Raw Parameters
 --------------
@@ -377,7 +380,8 @@ Raw Parameters
 Option 43 for UniFI
 -------------------
 
-* These parameters need to be part of the DHCP global options. They stay unchanged.
+* These parameters need to be part of the DHCP global options.
+  They stay unchanged.
 
 
 .. code-block:: none
@@ -456,6 +460,8 @@ IPv6 server
 VyOS also provides DHCPv6 server functionality which is described in this
 section.
 
+.. _dhcp-server:v6_config:
+
 Configuration
 =============
 
@@ -557,6 +563,8 @@ The configuration will look as follows:
           }
       }
 
+.. _dhcp-server:v6_static_mapping:
+
 Static mappings
 ---------------
 
@@ -603,6 +611,8 @@ The configuration will look as follows:
 
 .. start_vyoslinter
 
+.. _dhcp-server:v6_op_cmd:
+
 Operation Mode
 ==============
 
diff --git a/docs/configuration/service/dns.rst b/docs/configuration/service/dns.rst
index 5ee17490..ccf5a7d0 100644
--- a/docs/configuration/service/dns.rst
+++ b/docs/configuration/service/dns.rst
@@ -177,6 +177,8 @@ one involves a third party service, like DynDNS.com or any other similar
 website. This method uses HTTP requests to transmit the new IP address. You
 can configure both in VyOS.
 
+.. _dns:dynmaic_config:
+
 Configuration
 =============
 
@@ -218,6 +220,8 @@ Configuration
    Configure optional TTL value on the given resource record. This defaults to
    600 seconds.
 
+.. _dns:dynmaic_example:
+
 Example
 ^^^^^^^
 
diff --git a/docs/configuration/service/snmp.rst b/docs/configuration/service/snmp.rst
index 4a5a2780..36dc1787 100644
--- a/docs/configuration/service/snmp.rst
+++ b/docs/configuration/service/snmp.rst
@@ -139,6 +139,8 @@ The securityapproach in v3 targets:
 
 * Authentication – to verify that the message is from a valid source.
 
+.. _snmp:v3_example:
+
 Example
 ^^^^^^^
 
diff --git a/docs/configuration/system/name-server.rst b/docs/configuration/system/name-server.rst
index c105c712..f18cb5a3 100644
--- a/docs/configuration/system/name-server.rst
+++ b/docs/configuration/system/name-server.rst
@@ -57,6 +57,7 @@ list can be defined which will be used for domain searches.
 .. note:: Domain names can include letters, numbers, hyphens and periods
    with a maximum length of 253 characters.
 
+.. _name-server:domain-search-order_example:
 
 Example
 -------
diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst
index f3e498d4..b008a8d9 100644
--- a/docs/configuration/trafficpolicy/index.rst
+++ b/docs/configuration/trafficpolicy/index.rst
@@ -1114,6 +1114,7 @@ parameters.
    available and get suddenly dropped when other classes start using
    their assigned *bandwidth* share.
 
+.. _traffic_policy:shaper_example:
 
 Example
 ^^^^^^^
diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst
index f902c388..f2c7b162 100644
--- a/docs/configuration/vpn/dmvpn.rst
+++ b/docs/configuration/vpn/dmvpn.rst
@@ -176,6 +176,8 @@ The below referenced IP address `192.0.2.1` is used as example address
 representing a global unicast address under which the HUB can be contacted by
 each and every individual spoke.
 
+.. _dmvpn:example_configuration:
+
 Configuration
 =============
 
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
 ^^^^^^^^^^^^^
 
diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst
index ff896d07..09d2cfed 100644
--- a/docs/installation/virtual/libvirt.rst
+++ b/docs/installation/virtual/libvirt.rst
@@ -100,6 +100,8 @@ The virt-manager application is a desktop user interface for managing virtual
 machines through libvirt. On the linux open
 :abbr:`VMM (Virtual Machine Manager)`.
 
+.. _libvirt:virt-manager_iso:
+
 Deploy from ISO
 ---------------
 
@@ -130,6 +132,8 @@ Deploy from ISO
 
 .. figure:: /_static/images/virt-libvirt-06.png
 
+.. _libvirt:virt-manager_qcow2:
+
 Deploy from qcow2
 -----------------
 
diff --git a/docs/installation/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst
index 81d04f0d..f64bc8be 100644
--- a/docs/installation/vyos-on-baremetal.rst
+++ b/docs/installation/vyos-on-baremetal.rst
@@ -93,6 +93,8 @@ This guide was developed using an APU4C4 board with the following specs:
 
 The board can be powered via 12V from the front or via a 5V onboard connector.
 
+.. _vyos-on-baremetal:apu4_shopping:
+
 Shopping Cart
 -------------
 
@@ -224,6 +226,8 @@ implemented.
 Simply proceed with a regular image installation as described in
 :ref:`installation`.
 
+.. _vyos-on-baremetal:apu4_pictures:
+
 Pictures
 --------