✨ NEW: Add NeedsLookUpTableBuilder

docs/builders.rst

@@ -162,4 +162,4 @@ or
 
 .. hint::
 
-    As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build.
+    As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build.

docs/conf.py

@@ -380,6 +380,9 @@ def custom_defined_func():
 # build needs.json to make permalinks work
 needs_build_json = True
 
+# build needs_lut.json to make permalinks work
+needs_lut_build_json = True
+
 # Get and maybe set GitHub credentials for services.
 # This is needed as the rate limit for not authenticated users is too low for the amount of requests we
 # need to perform for this documentation

docs/configuration.rst

@@ -1870,7 +1870,7 @@ needs_permalink_file
 The option specifies the name of the permalink html file,
 which will be copied to the html build directory during build.
 
-The permalink web site will load a ``needs.json`` file as specified
+The permalink web site will load a ``needs.json`` or ``needs_lut.json`` file as specified
 by :ref:`needs_permalink_data` and re-direct the web browser to the html document
 of the need, which is specified by appending the need ID as a query
 parameter, e.g., ``http://localhost:8000/permalink.html?id=REQ_4711``. 
@@ -1902,6 +1902,7 @@ an absolute path (on the web server) or an URL.
 
 Default value: ``needs.json``
 
+You can choice option ``needs_lut.json`` as detail :ref:`needs_lut_build_json`
 
 .. _needs_constraints:
 
@@ -2338,3 +2339,22 @@ If true, need options like status, tags or links are collapsed and shown only af
 Default value: True
 
 Can be overwritten for each single need by setting :ref:`need_collapse`.
+
+.. __needs_lut_build_json:
+
+needs_lut_build_json
+~~~~~~~~~~~~~~~~~~~~~~~
+Builds a ``needs_lut.json`` file during other builds, like ``html``. Different from ``needs.json``, ``needs_lut.json`` only include list of key ``id`` and value in list [``docname``, ``external_url``].
+A helpful load data fastly when you need improve performance.
+Default: False
+
+Example:
+
+.. code-block:: python
+
+    needs_lut_build_json = False
+
+.. hint::
+
+   The created ``needs_lut.json`` file gets stored in the ``outdir`` of the current builder.
+   So if ``html`` is used as builder, the final location is e.g. ``_build/html/needs_lut.json``.

sphinx_needs/builder.py

@@ -1,3 +1,4 @@
+import json
 import os
 from typing import Iterable, Optional, Set
 
@@ -80,7 +81,6 @@ def get_target_uri(self, _docname: str, _typ: Optional[str] = None) -> str:
 
 
 def build_needs_json(app: Sphinx, _exception: Exception) -> None:
-
     env = unwrap(app.env)
 
     if not env.config.needs_build_json:
@@ -158,3 +158,66 @@ def build_needumls_pumls(app: Sphinx, _exception: Exception) -> None:
         needs_builder.set_environment(env)
 
     needs_builder.finish()
+
+
+class NeedsLookUpTableBuilder(Builder):
+    name = "needs_lut"
+    format = "json"
+    file_suffix = ".txt"
+    links_suffix = None
+
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
+        pass
+
+    def finish(self) -> None:
+        env = unwrap(self.env)
+        needs = env.needs_all_needs.values()
+        needs_dict = {}
+        for need in needs:
+            if need["is_external"]:
+                needs_dict[need["id"]] = need["external_url"]
+            else:
+                needs_dict[need["id"]] = need["docname"]
+
+        try:
+            fname = os.path.join(self.outdir, "needs_lut.json")
+            with open(fname, "w", encoding="utf-8") as f:
+                json.dump(needs_dict, f, indent=4)
+        except Exception as e:
+            log.error(f"Error during writing json file: {e}")
+        else:
+            log.info("Needs doc lookup table json successfully created")
+
+    def get_outdated_docs(self) -> Iterable[str]:
+        return []
+
+    def prepare_writing(self, _docnames: Set[str]) -> None:
+        pass
+
+    def write_doc_serialized(self, _docname: str, _doctree: nodes.document) -> None:
+        pass
+
+    def cleanup(self) -> None:
+        pass
+
+    def get_target_uri(self, _docname: str, _typ: Optional[str] = None) -> str:
+        return ""
+
+
+def build_needs_look_up_json(app: Sphinx, _exception: Exception) -> None:
+    env = unwrap(app.env)
+
+    if not env.config.needs_lut_build_json:
+        return
+
+    # Do not create an additional look up table json, if builder is already in use.
+    if isinstance(app.builder, NeedsLookUpTableBuilder):
+        return
+
+    try:
+        needs_lut_builder = NeedsLookUpTableBuilder(app, env)
+    except TypeError:
+        needs_lut_builder = NeedsLookUpTableBuilder(app)
+        needs_lut_builder.set_environment(env)
+
+    needs_lut_builder.finish()

sphinx_needs/needs.py

@@ -12,8 +12,10 @@
 from sphinx_needs.api.configuration import add_extra_option
 from sphinx_needs.builder import (
     NeedsBuilder,
+    NeedsLookUpTableBuilder,
     NeedumlsBuilder,
     build_needs_json,
+    build_needs_look_up_json,
     build_needumls_pumls,
 )
 from sphinx_needs.config import NEEDS_CONFIG
@@ -141,6 +143,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
 
     app.add_builder(NeedsBuilder)
     app.add_builder(NeedumlsBuilder)
+    app.add_builder(NeedsLookUpTableBuilder)
     app.add_config_value(
         "needs_types",
         [
@@ -256,6 +259,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
 
     app.add_config_value("needs_build_needumls", "", "html", types=[str])
 
+    app.add_config_value("needs_lut_build_json", False, "html", types=[bool])
+
     # Permalink related config values.
     # path to permalink.html; absolute path from web-root
     app.add_config_value("needs_permalink_file", "permalink.html", "html")
@@ -279,6 +284,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     #
     app.add_config_value("needs_debug_measurement", False, "html", types=[dict])
 
+    app.add_config_value("needs_permalink_url", None, "html")
     # Define nodes
     app.add_node(Need, html=(html_visit, html_depart), latex=(latex_visit, latex_depart))
     app.add_node(
@@ -370,6 +376,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect("build-finished", process_warnings)
     app.connect("build-finished", build_needs_json)
     app.connect("build-finished", build_needumls_pumls)
+    app.connect("build-finished", build_needs_look_up_json)
     app.connect("build-finished", debug.process_timing)
     app.connect("env-updated", install_lib_static_files)
     app.connect("env-updated", install_permalink_file)

sphinx_needs/templates/permalink.html

@@ -21,33 +21,57 @@
         }
 
         function main() {
-            loadJSON('{{ needs_file }}', function (response) {
-                const needs = JSON.parse(response);
-                const current_version = needs['current_version'];
-                const versions = needs['versions'];
-                const version = versions[current_version];
-                const needs_obj = version['needs'];
+            var needs_file = '{{ needs_file }}';
+            loadJSON(needs_file, function (response) {
+                if (needs_file == "needs_lut.json") {
+                    const needs = JSON.parse(response);
+                    const id = getParameterByName('id');
+                    var pathname = new URL(window.location.href).pathname;
+                    pathname = pathname.substring(0, pathname.lastIndexOf('permalink.html'));
+                    const keys = Object.keys(needs);
+                    var docname = 'index';
+                    keys.forEach((key, index) => {
+                        if (key === id) {
+                            docname = needs[key];
+                            return;
+                        }
+                    });
 
-                const id = getParameterByName('id');
-                var pathname = new URL(window.location.href).pathname;
-                pathname = pathname.substring(0, pathname.lastIndexOf('{{ permalink_file }}'));
+                    if (docname.includes("#" + id)) {
+                        window.location.replace(pathname + docname);
+                    } else {
+                        window.location.replace(pathname + docname + '.html#' + id);
+                    }
+                }
+                else {
+                    const needs = JSON.parse(response);
+                    const current_version = needs['current_version'];
+                    const versions = needs['versions'];
+                    const version = versions[current_version];
+                    const needs_obj = version['needs'];
 
-                const keys = Object.keys(needs_obj);
+                    const id = getParameterByName('id');
+                    var pathname = new URL(window.location.href).pathname;
+                    pathname = pathname.substring(0, pathname.lastIndexOf('{{ permalink_file }}'));
 
-                var docname = 'index';
+                    const keys = Object.keys(needs_obj);
 
-                keys.forEach((key, index) => {
-                    if (key === id) {
-                        const need = needs_obj[key];
-                        docname = need['docname'];
-                        return;
-                    }
-                });
+                    var docname = 'index';
+
+                    keys.forEach((key, index) => {
+                        if (key === id) {
+                            const need = needs_obj[key];
+                            docname = need['docname'];
+                            return;
+                        }
+                    });
 
-                window.location.replace(pathname + docname + '.html#' + id);
+                    window.location.replace(pathname + docname + '.html#' + id);
+                }
             });
-        }
 
+
+        }
         function getParameterByName(name, url = window.location.href) {
             name = name.replace(/[\[\]]/g, '\\$&');
             var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)'),
@@ -65,4 +89,4 @@
 <body>
 </body>
 
-</html>
+</html>

tests/test_needs_look_up.py

@@ -0,0 +1,19 @@
+import json
+from pathlib import Path
+
+import pytest
+
+
+@pytest.mark.parametrize(
+    "test_app", [{"buildername": "needs_lut", "srcdir": "doc_test/doc_needs_builder"}], indirect=True
+)
+def test_doc_needs_id_builder(test_app):
+    app = test_app
+    app.build()
+
+    needs_json = Path(app.outdir, "needs_lut.json")
+    with open(needs_json) as needs_file:
+        needs_file_content = needs_file.read()
+
+    needs_list = json.loads(needs_file_content)
+    assert needs_list["TC_NEG_001"]