✨ NEW: Add NeedsLookUpTableBuilder

docs/builders.rst

@@ -163,3 +163,53 @@ or
 .. hint::
 
     As an alternative, you can set the config option :ref:`needs_build_needumls` to export the needumls files during each build.
+
+.. _needs_lut_builder:
+
+needs_lut
+---------
+.. versionadded:: 1.4.0
+
+The **needs_lut** builder exports all found needs to a single json file, which only include list of key ``id`` and value of ``docname`` or ``external_url``.
+
+The build creates file called **needs_lut.json** inside the given build-folder.
+Usage
++++++
+
+.. code-block:: bash
+
+    sphinx-build -b needs_lut source_dir build_dir
+
+Format
+++++++
+
+.. code-block:: python
+
+    {
+        "extend_test_001": "directives/needextend",
+        "extend_test_002": "directives/needextend",
+
+        "req_arch_001": "directives/needarch",
+        "req_arch_004": "directives/needarch",
+
+        "spec_arch_001": "directives/needarch",
+        "test_arch_001": "directives/needarch",
+        "COMP_T_001": "directives/needarch",
+        "COMP_T_002": "directives/needarch",
+
+        "EX_REQ_1": "examples/index",
+        "EX_REQ_2": "examples/index",
+
+        "R_F4722": "examples/index",
+        "OWN_ID_123": "examples/index",
+        "IMPL_01": "examples/index",
+        "T_C3893": "examples/index",
+        "R_2A9D0": "filter",
+        "R_22EB2": "filter",
+        "S_D70B0": "filter",
+        "S_01A67": "filter",
+        "T_5CCAA": "filter",
+        "R_17EB4": "filter",
+        "req_flow_001": "directives/needflow",
+        "spec_flow_001": "directives/needflow",
+    }

docs/changelog.rst

@@ -15,6 +15,7 @@ Released: under development
 1.4.0
 -----
 Released: under development
+* Improvement: Added Builder :ref:`needs_lut_builder` and config option :ref:`needs_lut_build_json` in `conf.py`.
 
 * Improvement: Reduce document build time, by memoizing the inline parse in ``build_need`` (`#968 <https://github.com/useblocks/sphinx-needs/pull/968>`_)
 

docs/conf.py

@@ -361,6 +361,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 = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/configuration.rst

@@ -1821,7 +1821,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``. 
@@ -1853,6 +1853,7 @@ an absolute path (on the web server) or an URL.
 
 Default value: ``needs.json``
 
+You can choose needs_lut_build_json  ``needs_lut.json`` after setting :ref:`needs_lut_build_json`
 
 .. _needs_constraints:
 
@@ -2289,3 +2290,25 @@ 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
+~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.4.0
+
+Builds a ``needs_lut.json`` file during other builds (like ``html``), which is different from ``needs.json``, only include list of key ``id`` and value of ``docname`` or ``external_url``.
+This is helpful for loading 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
 
@@ -157,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 = "needs"
+    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 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",
         [
@@ -258,11 +261,15 @@ 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")
     # path to needs.json relative to permalink.html
-    app.add_config_value("needs_permalink_data", "needs.json", "html")
+    app.add_config_value("needs_permalink_data", "needs_lut.json", "html")
+    # add config mode permalink
+    app.add_config_value("needs_lut_mode", False, "html", types=[bool])
     # path to needs_report_template file which is based on the conf.py directory.
     app.add_config_value("needs_report_template", "", "html", types=[str])
 
@@ -281,6 +288,8 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     #
     app.add_config_value("needs_debug_measurement", False, "html", types=[dict])
 
+    app.add_config_value("needs_lut_build", False, "html", types=[bool])
+
     # Define nodes
     app.add_node(Need, html=(html_visit, html_depart), latex=(latex_visit, latex_depart))
     app.add_node(
@@ -372,6 +381,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

@@ -23,31 +23,55 @@
         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'];
+                if(needs.hasOwnProperty("current_version")) {
+                    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 id = getParameterByName('id');
-                var pathname = new URL(window.location.href).pathname;
-                pathname = pathname.substring(0, pathname.lastIndexOf('{{ permalink_file }}'));
+                    const id = getParameterByName('id');
+                    var pathname = new URL(window.location.href).pathname;
+                    pathname = pathname.substring(0, pathname.lastIndexOf('{{ permalink_file }}'));
 
-                const keys = Object.keys(needs_obj);
+                    const keys = Object.keys(needs_obj);
 
-                var docname = 'index';
+                    var docname = 'index';
 
-                keys.forEach((key, index) => {
-                    if (key === id) {
-                        const need = needs_obj[key];
-                        docname = need['docname'];
-                        return;
-                    }
-                });
+                    keys.forEach((key, index) => {
+                        if (key === id) {
+                            const need = needs_obj[key];
+                            docname = need['docname'];
+                            return;
+                        }
+                    });
+
+                    window.location.replace(pathname + docname + '.html#' + id);
+                }
+                else {
+                    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;
+                        }
+                    });
 
-                window.location.replace(pathname + docname + '.html#' + id);
+                    if (docname.includes("#" + id)) {
+                        window.location.replace(pathname + docname);
+                    } else {
+                        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"]