make extractor_userdocs a Sphinx extension

doc/htmldoc/_ext/extractor_userdocs.py

@@ -272,7 +272,7 @@ def CreateTagIndices(self) -> list[str]:
             #log.debug("%3d docs in index for %s...", nfiles, str(current_tags))
             log.debug("generating index for %s...", str(current_tags))
             indextext = rst_index(hier, current_tags)
-            with open(os.path.join(outdir, indexname), "w") as outfile:
+            with open(os.path.join(self._outdir, indexname), "w") as outfile:
                 outfile.write(indextext)
             indexfiles.append(indexname)
         log.info("%4d non-empty index files generated", len(indexfiles))
@@ -603,6 +603,58 @@ def output_exit(result):
     sys.exit(0)
 
 
+def ExtractUserDocs(listoffiles, basedir="..", outdir="userdocs/"):
+    """
+    Extract and build all user documentation and build tag indices.
+    Writes extracted information to JSON files in outdir. In particular the
+    list of seen tags mapped to files they appear in, and the indices generated
+    from all combinations of tags.
+    Parameters are the same as for `UserDocExtractor` and are handed to it
+    unmodified.
+    Returns
+    -------
+    None
+    """
+    data = JsonWriter(outdir)
+    # Gather all information and write RSTs
+    extractor = UserDocExtractor(outdir=outdir, basedir=basedir)
+    extractor.extract_all(listoffiles)
+    tags = extractor.tagdict
+    data.write(tags, "tags")
+
+    indexfiles = extractor.CreateTagIndices()
+
+    data.write(indexfiles, "indexfiles")
+
+    toc_list = [name[:-4] for names in tags.values() for name in names]
+    idx_list = [indexfile[:-4] for indexfile in indexfiles]
+
+    with open(os.path.join(outdir, "toc-tree.json"), "w") as tocfile:
+        json.dump(list(set(toc_list)) + list(set(idx_list)), tocfile)
+
+
+def config_inited_handler(app, config):
+    """
+    This is the entrypoint called by the registered Sphinx hook.
+    """
+    models_rst_dir = os.path.abspath("models")
+    repo_root_dir = os.path.abspath("../..")
+    ExtractUserDocs(
+        listoffiles=relative_glob("models/*.h", "nestkernel/*.h", basedir=repo_root_dir),
+        basedir=repo_root_dir,
+        outdir=models_rst_dir,
+    )
+
+
+def setup(app):
+    app.connect("config-inited", config_inited_handler)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+
 if __name__ == "__main__":
     globs = ("models/*.h", "nestkernel/*.h")
     basedir = ".."

doc/htmldoc/conf.py

@@ -32,8 +32,6 @@
 extension_module_dir = os.path.abspath("./_ext")
 sys.path.append(extension_module_dir)
 
-from extractor_userdocs import ExtractUserDocs, relative_glob  # noqa
-
 repo_root_dir = os.path.abspath("../..")
 pynest_dir = os.path.join(repo_root_dir, "pynest")
 # Add the NEST Python module to the path (just the py files, the binaries are mocked)
@@ -63,6 +61,7 @@
     "VersionSyncRole",
     "sphinx_copybutton",
     "notfound.extension",
+    "extractor_userdocs",
 ]
 
 autodoc_mock_imports = ["nest.pynestkernel", "nest.ll_api"]
@@ -208,14 +207,6 @@
 }
 
 
-def config_inited_handler(app, config):
-    models_rst_dir = os.path.abspath("models")
-    ExtractUserDocs(
-        listoffiles=relative_glob("models/*.h", "nestkernel/*.h", basedir=repo_root_dir),
-        basedir=repo_root_dir,
-        outdir=models_rst_dir,
-    )
-
 
 def toc_customizer(app, docname, source):
     if docname == "models/models-toc":
@@ -233,7 +224,6 @@ def setup(app):
     app.add_css_file("css/custom.css")
     app.add_css_file("css/pygments.css")
     app.add_js_file("js/custom.js")
-    app.connect("config-inited", config_inited_handler)
 
 
 nitpick_ignore = [