From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id D5B1464E52 for ; Tue, 21 Jul 2020 13:26:26 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id C31E717B13 for ; Tue, 21 Jul 2020 13:25:56 +0200 (CEST) Received: from gaia.proxmox.com (212-186-127-178.static.upcbusiness.at [212.186.127.178]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id A5C0717B0B for ; Tue, 21 Jul 2020 13:25:55 +0200 (CEST) Received: from gaia.proxmox.com (localhost.localdomain [127.0.0.1]) by gaia.proxmox.com (8.15.2/8.15.2/Debian-14~deb10u1) with ESMTP id 06LBPt3r315264; Tue, 21 Jul 2020 13:25:55 +0200 Received: (from oguz@localhost) by gaia.proxmox.com (8.15.2/8.15.2/Submit) id 06LBPtgH315263; Tue, 21 Jul 2020 13:25:55 +0200 From: Oguz Bektas To: pbs-devel@lists.proxmox.com Date: Tue, 21 Jul 2020 13:25:53 +0200 Message-Id: <20200721112553.315212-1-o.bektas@proxmox.com> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -1.174 Adjusted score from AWL reputation of From: address KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_LAZY_DOMAIN_SECURITY 1 Sending domain does not have any anti-forgery methods KHOP_HELO_FCRDNS 0.251 Relay HELO differs from its IP's reverse DNS NO_DNS_FOR_FROM 0.379 Envelope sender has no MX or A DNS records SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an SPF Record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [sphinx-doc.org, conf.py, sphinx.builders, proxmox-scanrefs.py] Subject: [pbs-devel] [PATCH proxmox-backup] docs: add prototype sphinx extension for online help X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 21 Jul 2020 11:26:26 -0000 goes through the sections in the documents and creates the OnlineHelpInfo.js file from the explicitly defined section labels. run "make scanrefs" in the docs folder to generate the output. for example: const pveOnlineHelpInfo = { "create-backups": { "link": "/docs/administration-guide.html#create-backups", "title": "Creating Backups" }, "pruning": { "link": "/docs/administration-guide.html#pruning", "title": "Pruning and Removing Backups" }, "id1": { "link": "/docs/administration-guide.html#id1", "title": "Garbage Collection" }, "pve-integration": { "link": "/docs/administration-guide.html#pve-integration", "title": "`Proxmox VE`_ integration" }, "pxar-format": { "link": "/docs/file-formats.html#pxar-format", "title": "Proxmox File Archive Format (``.pxar``)" }, "sysadmin-package-repositories": { "link": "/docs/package-repositories.html#sysadmin-package-repositories", "title": "Debian Package Repositories" }, "fake-label": { "link": "/docs/sysadmin.html#fake-label", "title": "Hardware" } }; --- docs/Makefile | 4 ++ docs/_ext/proxmox-scanrefs.py | 90 +++++++++++++++++++++++++++++++++++ docs/conf.py | 7 ++- 3 files changed, 99 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..bb0c532d --- /dev/null +++ b/docs/_ext/proxmox-scanrefs.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 + +# debugging stuff +from pprint import pprint + +from typing import cast + +import json +import re + +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 = [] + self.env.online_help = {} + + if not os.path.isdir(self.outdir): + os.mkdir(self.outdir) + + self.output_filename = os.path.join(self.outdir, 'OnlineHelpInfo.js') + 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') and len(node['ids']) > 1: # explicit labels + filename = self.env.doc2path(docname) + filename_html = re.sub('.rst', '.html', filename) + labelid = node['ids'][1] # [0] is predefined by sphinx, we need [1] for explicit ones + title = cast(nodes.title, node[0]) + logger.info(f'traversing section {title.astext()}') + ref_name = getattr(title, 'rawsource', title.astext()) + + self.env.online_help[labelid]: dict = {'link': '', 'title': ''} + self.env.online_help[labelid]['link'] = "/docs/" + os.path.basename(filename_html) + f"#{labelid}" + self.env.online_help[labelid]['title'] = ref_name + + 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): + # generate OnlineHelpInfo.js output + self.output.write("const pveOnlineHelpInfo = ") + self.output.write(json.dumps(self.env.online_help, indent=2)) + self.output.write(";\n") + 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