* [pve-devel] [PATCH v3 proxmox-backup] docs: add prototype sphinx extension for online help
@ 2020-09-02 10:37 ` Oguz Bektas
0 siblings, 0 replies; 2+ messages in thread
From: Oguz Bektas @ 2020-09-02 10:37 UTC (permalink / raw)
To: pve-devel, pbs-devel
goes through the sections in the documents and creates the
OnlineHelpInfo.js file from the explicitly defined section labels which
are used in the js files with 'onlineHelp' variable.
---
v2->v3:
* use $(MAKE) in makefile
* error for unused anchors in onlinehelp
* always have 'pbs_documentation_index'
docs/Makefile | 7 +-
docs/_ext/proxmox-scanrefs.py | 133 ++++++++++++++++++++++++++++++++++
docs/conf.py | 7 +-
docs/local-zfs.rst | 3 +
www/Makefile | 4 +
www/OnlineHelpInfo.js | 14 ++--
6 files changed, 160 insertions(+), 8 deletions(-)
create mode 100644 docs/_ext/proxmox-scanrefs.py
diff --git a/docs/Makefile b/docs/Makefile
index 34ec8809..8d1e8a1b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -28,7 +28,6 @@ COMPILEDIR := ../target/debug
SPHINXOPTS += -t devbuild
endif
-
# Sphinx internal variables.
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
@@ -68,6 +67,12 @@ 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: onlinehelpinfo
+onlinehelpinfo:
+ @echo "Generating OnlineHelpInfo.js..."
+ $(SPHINXBUILD) -b proxmox-scanrefs $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
+ @echo "Build finished. OnlineHelpInfo.js is in $(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..26e0fe77
--- /dev/null
+++ b/docs/_ext/proxmox-scanrefs.py
@@ -0,0 +1,133 @@
+#!/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 #my-label in the html,
+# even if the section name changes.
+#
+# see https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
+
+def scan_extjs_files(wwwdir="../www"): # a bit rough i know, but we can optimize later
+ js_files = []
+ used_anchors = []
+ logger.info("scanning extjs files for onlineHelp definitions")
+ for root, dirs, files in os.walk("{}".format(wwwdir)):
+ #print(root, dirs, files)
+ for filename in files:
+ if filename.endswith('.js'):
+ js_files.append(os.path.join(root, filename))
+ for js_file in js_files:
+ fd = open(js_file).read()
+ match = re.search("onlineHelp:\s*[\'\"](.*?)[\'\"]", fd) # match object is tuple
+ if match:
+ anchor = match.groups()[0]
+ anchor = re.sub('_', '-', anchor) # normalize labels
+ logger.info("found onlineHelp: {} in {}".format(anchor, js_file))
+ used_anchors.append(anchor)
+ return used_anchors
+
+
+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 = {}
+ self.env.online_help['pbs_documentation_index'] = {
+ 'link': '/pbs-docs/index.html',
+ 'title': 'Proxmox Backup Server Documentation Index',
+ }
+ self.env.used_anchors = scan_extjs_files()
+
+ 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('traversing section {}'.format(title.astext()))
+ ref_name = getattr(title, 'rawsource', title.astext())
+
+ self.env.online_help[labelid] = {'link': '', 'title': ''}
+ self.env.online_help[labelid]['link'] = "/docs/" + os.path.basename(filename_html) + "#{}".format(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 validate_anchors(self):
+ #pprint(self.env.online_help)
+ to_remove = []
+ for anchor in self.env.used_anchors:
+ if anchor not in self.env.online_help:
+ logger.info("[-] anchor {} is missing from onlinehelp!".format(anchor))
+ for anchor in self.env.online_help:
+ if anchor not in self.env.used_anchors and anchor != 'pbs_documentation_index':
+ logger.info("[*] anchor {} not used! deleting...".format(anchor))
+ to_remove.append(anchor)
+ for anchor in to_remove:
+ self.env.online_help.pop(anchor, None)
+ return
+
+ def finish(self):
+ # generate OnlineHelpInfo.js output
+ self.validate_anchors()
+
+ self.output.write("const proxmoxOnlineHelpInfo = ")
+ 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
diff --git a/docs/local-zfs.rst b/docs/local-zfs.rst
index 41633fd8..cd9d5315 100644
--- a/docs/local-zfs.rst
+++ b/docs/local-zfs.rst
@@ -1,3 +1,6 @@
+
+.. _chapter-zfs:
+
ZFS on Linux
------------
diff --git a/www/Makefile b/www/Makefile
index edce8cb3..992c4957 100644
--- a/www/Makefile
+++ b/www/Makefile
@@ -54,6 +54,10 @@ all: js/proxmox-backup-gui.js css/ext6-pbs.css
js:
mkdir js
+OnlineHelpInfo.js:
+ $(MAKE) -C ../docs onlinehelpinfo
+ mv ../docs/output/scanrefs/OnlineHelpInfo.js .
+
js/proxmox-backup-gui.js: js OnlineHelpInfo.js ${JSSRC}
cat OnlineHelpInfo.js ${JSSRC} >$@.tmp
mv $@.tmp $@
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index bb48bab6..c7c6363f 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -1,6 +1,10 @@
-var proxmoxOnlineHelpInfo = {
- "pbs_documentation_index" : {
- "link" : "/pbs-docs/index.html",
- "title" : "Proxmox Backup Server Documentation Index"
- }
+const proxmoxOnlineHelpInfo = {
+ "pbs_documentation_index": {
+ "link": "/pbs-docs/index.html",
+ "title": "Proxmox Backup Server Documentation Index"
+ },
+ "chapter-zfs": {
+ "link": "/docs/sysadmin.html#chapter-zfs",
+ "title": "ZFS on Linux"
+ }
};
--
2.20.1
^ permalink raw reply [flat|nested] 2+ messages in thread
* [pbs-devel] [PATCH v3 proxmox-backup] docs: add prototype sphinx extension for online help
@ 2020-09-02 10:37 ` Oguz Bektas
0 siblings, 0 replies; 2+ messages in thread
From: Oguz Bektas @ 2020-09-02 10:37 UTC (permalink / raw)
To: pve-devel, pbs-devel
goes through the sections in the documents and creates the
OnlineHelpInfo.js file from the explicitly defined section labels which
are used in the js files with 'onlineHelp' variable.
---
v2->v3:
* use $(MAKE) in makefile
* error for unused anchors in onlinehelp
* always have 'pbs_documentation_index'
docs/Makefile | 7 +-
docs/_ext/proxmox-scanrefs.py | 133 ++++++++++++++++++++++++++++++++++
docs/conf.py | 7 +-
docs/local-zfs.rst | 3 +
www/Makefile | 4 +
www/OnlineHelpInfo.js | 14 ++--
6 files changed, 160 insertions(+), 8 deletions(-)
create mode 100644 docs/_ext/proxmox-scanrefs.py
diff --git a/docs/Makefile b/docs/Makefile
index 34ec8809..8d1e8a1b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -28,7 +28,6 @@ COMPILEDIR := ../target/debug
SPHINXOPTS += -t devbuild
endif
-
# Sphinx internal variables.
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
@@ -68,6 +67,12 @@ 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: onlinehelpinfo
+onlinehelpinfo:
+ @echo "Generating OnlineHelpInfo.js..."
+ $(SPHINXBUILD) -b proxmox-scanrefs $(ALLSPHINXOPTS) $(BUILDDIR)/scanrefs
+ @echo "Build finished. OnlineHelpInfo.js is in $(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..26e0fe77
--- /dev/null
+++ b/docs/_ext/proxmox-scanrefs.py
@@ -0,0 +1,133 @@
+#!/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 #my-label in the html,
+# even if the section name changes.
+#
+# see https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
+
+def scan_extjs_files(wwwdir="../www"): # a bit rough i know, but we can optimize later
+ js_files = []
+ used_anchors = []
+ logger.info("scanning extjs files for onlineHelp definitions")
+ for root, dirs, files in os.walk("{}".format(wwwdir)):
+ #print(root, dirs, files)
+ for filename in files:
+ if filename.endswith('.js'):
+ js_files.append(os.path.join(root, filename))
+ for js_file in js_files:
+ fd = open(js_file).read()
+ match = re.search("onlineHelp:\s*[\'\"](.*?)[\'\"]", fd) # match object is tuple
+ if match:
+ anchor = match.groups()[0]
+ anchor = re.sub('_', '-', anchor) # normalize labels
+ logger.info("found onlineHelp: {} in {}".format(anchor, js_file))
+ used_anchors.append(anchor)
+ return used_anchors
+
+
+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 = {}
+ self.env.online_help['pbs_documentation_index'] = {
+ 'link': '/pbs-docs/index.html',
+ 'title': 'Proxmox Backup Server Documentation Index',
+ }
+ self.env.used_anchors = scan_extjs_files()
+
+ 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('traversing section {}'.format(title.astext()))
+ ref_name = getattr(title, 'rawsource', title.astext())
+
+ self.env.online_help[labelid] = {'link': '', 'title': ''}
+ self.env.online_help[labelid]['link'] = "/docs/" + os.path.basename(filename_html) + "#{}".format(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 validate_anchors(self):
+ #pprint(self.env.online_help)
+ to_remove = []
+ for anchor in self.env.used_anchors:
+ if anchor not in self.env.online_help:
+ logger.info("[-] anchor {} is missing from onlinehelp!".format(anchor))
+ for anchor in self.env.online_help:
+ if anchor not in self.env.used_anchors and anchor != 'pbs_documentation_index':
+ logger.info("[*] anchor {} not used! deleting...".format(anchor))
+ to_remove.append(anchor)
+ for anchor in to_remove:
+ self.env.online_help.pop(anchor, None)
+ return
+
+ def finish(self):
+ # generate OnlineHelpInfo.js output
+ self.validate_anchors()
+
+ self.output.write("const proxmoxOnlineHelpInfo = ")
+ 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
diff --git a/docs/local-zfs.rst b/docs/local-zfs.rst
index 41633fd8..cd9d5315 100644
--- a/docs/local-zfs.rst
+++ b/docs/local-zfs.rst
@@ -1,3 +1,6 @@
+
+.. _chapter-zfs:
+
ZFS on Linux
------------
diff --git a/www/Makefile b/www/Makefile
index edce8cb3..992c4957 100644
--- a/www/Makefile
+++ b/www/Makefile
@@ -54,6 +54,10 @@ all: js/proxmox-backup-gui.js css/ext6-pbs.css
js:
mkdir js
+OnlineHelpInfo.js:
+ $(MAKE) -C ../docs onlinehelpinfo
+ mv ../docs/output/scanrefs/OnlineHelpInfo.js .
+
js/proxmox-backup-gui.js: js OnlineHelpInfo.js ${JSSRC}
cat OnlineHelpInfo.js ${JSSRC} >$@.tmp
mv $@.tmp $@
diff --git a/www/OnlineHelpInfo.js b/www/OnlineHelpInfo.js
index bb48bab6..c7c6363f 100644
--- a/www/OnlineHelpInfo.js
+++ b/www/OnlineHelpInfo.js
@@ -1,6 +1,10 @@
-var proxmoxOnlineHelpInfo = {
- "pbs_documentation_index" : {
- "link" : "/pbs-docs/index.html",
- "title" : "Proxmox Backup Server Documentation Index"
- }
+const proxmoxOnlineHelpInfo = {
+ "pbs_documentation_index": {
+ "link": "/pbs-docs/index.html",
+ "title": "Proxmox Backup Server Documentation Index"
+ },
+ "chapter-zfs": {
+ "link": "/docs/sysadmin.html#chapter-zfs",
+ "title": "ZFS on Linux"
+ }
};
--
2.20.1
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-09-02 10:38 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-02 10:37 [pve-devel] [PATCH v3 proxmox-backup] docs: add prototype sphinx extension for online help Oguz Bektas
2020-09-02 10:37 ` [pbs-devel] " Oguz Bektas
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