✨ NEW: Add NeedsLookUpTableBuilder

docs/builders.rst

@@ -180,4 +180,55 @@ Usage
 
 .. code-block:: bash
 
-    sphinx-build -b needs_id source_dir build_dir
+    sphinx-build -b needs_id source_dir build_dir
+
+
+.. _needs_lut_builder:
+
+needs_lut
+---------
+.. versionadded:: 1.4.0
+
+The **needs_lut** (Needs Lookup Table) 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 a 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,8 @@ 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: Added Builder :ref:`needs_id_builder` added and config option :ref:`needs_build_json_per_id` 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

@@ -364,6 +364,9 @@ def custom_defined_func():
 # build needs_json for every needs-id to make detail panel
 needs_build_json_per_id = False
 
+# 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

@@ -1865,7 +1865,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``. 
@@ -1897,6 +1897,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:
 
@@ -2333,3 +2334,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

@@ -230,3 +230,77 @@ def build_needs_id_json(app: Sphinx, _exception: Exception) -> None:
         needs_id_builder.set_environment(env)
 
     needs_id_builder.finish()
+
+
+class NeedsLookUpTableBuilder(Builder):
+    """
+    JSON builder for needs, which creates a simple JSON file including only all keys is need' id and the value is doc name or external_url
+    """
+
+    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 = self.env
+        data = SphinxNeedsData(env)
+        needs = data.get_or_create_needs().values()  # We need a list of needs for later filter checks
+        needs_dict = {}
+        needs_config = NeedsSphinxConfig(env.config)
+        filter_string = needs_config.builder_filter
+        from sphinx_needs.filter_common import filter_needs
+
+        filtered_needs = filter_needs(self.app, needs, filter_string)
+        for need in filtered_needs:
+            if need["is_external"]:
+                needs_dict[need["id"]] = need["external_url"]
+            else:
+                needs_dict[need["id"]] = need["docname"]
+
+        version = getattr(env.config, "version", "unset")
+        needs_list = NeedsList(env.config, self.outdir, self.srcdir)
+        needs_list.add_lut_need(version, needs_dict)
+        try:
+            needs_list.write_json("needs_lut.json")
+        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 = app.env
+
+    if not NeedsSphinxConfig(env.config).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/config.py

@@ -252,6 +252,7 @@ def __setattr__(self, name: str, value: Any) -> None:
     # add config for needs_id_builder
     build_json_per_id: bool = field(default=False, metadata={"rebuild": "html", "types": (bool,)})
     build_json_per_id_path: str = field(default="needs_id", metadata={"rebuild": "html", "types": (str,)})
+    lut_build_json: bool = field(default=False, metadata={"rebuild": "html", "types": (bool,)})
 
     @classmethod
     def add_config_values(cls, app: Sphinx) -> None:

sphinx_needs/needs.py

@@ -12,9 +12,11 @@
 from sphinx_needs.builder import (
     NeedsBuilder,
     NeedsIdBuilder,
+    NeedsLookUpTableBuilder,
     NeedumlsBuilder,
     build_needs_id_json,
     build_needs_json,
+    build_needs_look_up_json,
     build_needumls_pumls,
 )
 from sphinx_needs.config import NEEDS_CONFIG, NeedsSphinxConfig
@@ -142,7 +144,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_builder(NeedsBuilder)
     app.add_builder(NeedumlsBuilder)
     app.add_builder(NeedsIdBuilder)
-
+    app.add_builder(NeedsLookUpTableBuilder)
     NeedsSphinxConfig.add_config_values(app)
 
     # Define nodes
@@ -245,6 +247,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.connect("build-finished", build_needs_json)
     app.connect("build-finished", build_needs_id_json)
     app.connect("build-finished", build_needumls_pumls)
+    app.connect("build-finished", build_needs_look_up_json)
     app.connect("build-finished", debug.process_timing)
 
     # Be sure Sphinx-Needs config gets erased before any events or external API calls get executed.

sphinx_needs/needsfile.py

@@ -7,7 +7,7 @@
 import os
 import sys
 from datetime import datetime
-from typing import Any, List
+from typing import Any, Dict, List
 
 from jsonschema import Draft7Validator
 from sphinx.config import Config
@@ -131,6 +131,9 @@ def load_json(self, file: str) -> None:
 
             self.log.debug(f"needs.json file loaded: {file}")
 
+    def add_lut_need(self, version: str, needs_lut: Dict[str, Any]) -> None:
+        self.needs_list = needs_lut
+
 
 class Errors:
     def __init__(self, schema_errors: List[Any]):

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_lut_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"]