[pbs-devel] [PATCH proxmox-backup] docs: add prototype sphinx extension for explicitly defined section labels

[Oguz Bektas <o.bektas@proxmox.com>]

goes through the sections in the documents and creates an output.txt
file with the following contents:
filename, line, title, refname, labelid

for example:

filename: /home/oguz/Git/rust/proxmox-backup/docs/package-repositories.rst
line: 4
title: <title>Debian Package Repositories</title>
refname: Debian Package Repositories
labelid: sysadmin-package-repositories

should be enough information to generate the OnlineHelp map. (anchor is
same as labelid)
---
 docs/Makefile                 |  4 ++
 docs/_ext/proxmox-scanrefs.py | 83 +++++++++++++++++++++++++++++++++++
 docs/conf.py                  |  7 ++-
 3 files changed, 92 insertions(+), 2 deletions(-)
 create mode 100644 docs/_ext/proxmox-scanrefs.py

diff --git a/docs/Makefile b/docs/Makefile
index 34ec8809..796861b1 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -68,6 +68,10 @@ proxmox-backup-manager.1: proxmox-backup-manager/man1.rst  proxmox-backup-manage
 proxmox-backup-proxy.1: proxmox-backup-proxy/man1.rst  proxmox-backup-proxy/description.rst
 	rst2man $< >$@
 
+.PHONY: scanrefs
+scanrefs:
+	$(SPHINXBUILD) -b proxmox-scanrefs $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
+
 .PHONY: html
 html: ${GENERATED_SYNOPSIS}
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
diff --git a/docs/_ext/proxmox-scanrefs.py b/docs/_ext/proxmox-scanrefs.py
new file mode 100644
index 00000000..c45de14f
--- /dev/null
+++ b/docs/_ext/proxmox-scanrefs.py
@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+
+# debugging stuff
+from pprint import pprint
+
+from typing import cast
+
+import os
+import io
+from docutils import nodes
+
+from sphinx.builders import Builder
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+# refs are added in the following manner before the title of a section (note underscore and newline before title):
+# .. _my-label:
+#
+# Section to ref
+# --------------
+#
+#
+# then referred to like (note missing underscore):
+# "see :ref:`my-label`"
+#
+# the benefit of using this is if a label is explicitly set for a section,
+# we can refer to it with this anchor even if the section name changes.
+#
+# see https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
+
+def setup(app):
+    logger.info('Mapping reference labels...')
+    app.add_builder(ReflabelMapper)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+class ReflabelMapper(Builder):
+    name = 'proxmox-scanrefs'
+
+    def init(self):
+        self.docnames = []
+
+        if not os.path.isdir(self.outdir):
+            os.mkdir(self.outdir)
+
+        self.output_filename = os.path.join(self.outdir, 'output.txt')
+        self.output = io.open(self.output_filename, 'w', encoding='UTF-8')
+
+    def write_doc(self, docname, doctree):
+            for node in doctree.traverse(nodes.section):
+                #pprint(vars(node))
+
+                if hasattr(node, 'expect_referenced_by_id'): # only explicitly defined labels
+                    labelid = node['ids'][1]
+                    title = cast(nodes.title, node[0])
+                    logger.info(f'traversing section {title}')
+                    ref_name = getattr(title, 'rawsource', title.astext())
+
+                    self.output.write(u"\n\nfilename: %s\nline: %s\ntitle: %s\nrefname: %s\nlabelid: %s\n" % (
+                        self.env.doc2path(docname),
+                        node.line,
+                        title,
+                        ref_name,
+                        labelid
+                    ))
+            return
+
+    def get_outdated_docs(self):
+        return 'all documents'
+
+    def prepare_writing(self, docnames):
+        return
+
+    def get_target_uri(self, docname, typ=None):
+        return ''
+
+    def finish(self):
+        self.output.close()
+        return
diff --git a/docs/conf.py b/docs/conf.py
index 0c40ffb5..a9d45c2e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,9 +18,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import sys
+import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+# custom extensions
+sys.path.append(os.path.abspath("./_ext"))
+
 # -- Implement custom formatter for code-blocks ---------------------------
 #
 # * use smaller font
@@ -46,7 +49,7 @@ PygmentsBridge.latex_formatter = CustomLatexFormatter
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 
-extensions = ["sphinx.ext.graphviz", "sphinx.ext.todo"]
+extensions = ["sphinx.ext.graphviz", "sphinx.ext.todo", "proxmox-scanrefs"]
 
 todo_link_only = True
 
-- 
2.20.1