all lists on lists.proxmox.com
 help / color / mirror / Atom feed
* [pbs-devel] [PATCH proxmox-backup] docs: add prototype sphinx extension for explicitly defined section labels
@ 2020-07-20 14:03 Oguz Bektas
  2020-07-20 14:46 ` Thomas Lamprecht
  2020-07-20 15:27 ` Dietmar Maurer
  0 siblings, 2 replies; 3+ messages in thread
From: Oguz Bektas @ 2020-07-20 14:03 UTC (permalink / raw)
  To: pbs-devel

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




^ permalink raw reply	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-07-20 15:28 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-07-20 14:03 [pbs-devel] [PATCH proxmox-backup] docs: add prototype sphinx extension for explicitly defined section labels Oguz Bektas
2020-07-20 14:46 ` Thomas Lamprecht
2020-07-20 15:27 ` Dietmar Maurer

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal