Merge pull request #2159 from strictdoc-project/stanislaw/2100_export_doctree_as_js_map

 html export: export project_map.js, add stable_uri_forwarder.js

Author: stanislaw

strictdoc/core/document_tree_iterator.py

@@ -10,7 +10,7 @@ def __init__(self, document_tree) -> None:
         assert isinstance(document_tree, DocumentTree)
         self.document_tree: DocumentTree = document_tree
 
-    def is_empty_tree(self):
+    def is_empty_tree(self) -> bool:
         return len(self.document_tree.document_list) == 0
 
     def iterator(self):

strictdoc/export/html/_static/controllers/copy_stable_link_button_controller.js

@@ -7,55 +7,76 @@
       button.addEventListener("click", (event) => {
         event.preventDefault();
 
-        const clip = button.dataset.path;
+        const link = button.dataset.path;
 
         const copyIcon = this.element.querySelector(".copy_to_clipboard-copy_icon");
         const doneIcon = this.element.querySelector(".copy_to_clipboard-done_icon");
-        _updateClipboard(
-          clip,
-          _confirm(button, copyIcon, doneIcon)
-        )
+
+        // Resolve any relative URLs with respect to current URL.
+        const resolved = (
+          this._isAbsoluteURL(link)
+          ? link
+          : new URL(link, window.location.href).href
+        );
+
+        // Expand folder to index if we run from the local file system.
+        const expanded = (
+          (window.location.protocol === 'file:')
+          ? resolved.replace(/#/, 'index.html#')
+          : resolved
+        );
+
+        this._updateClipboard(expanded, this._confirmCopy(button, copyIcon, doneIcon));
       });
     }
-  }
 
-  Stimulus.application.register("copy_stable_link_button", CopyStableLinkController);
+    _isAbsoluteURL(url) {
+      try {
+        new URL(url); // throws if it's relative
+        return true;
+      } catch {
+        return false;
+      }
+    }
 
-  function _updateClipboard(newClip, callback) {
-    navigator.clipboard.writeText(newClip).then(() => {
-      /* clipboard successfully set */
-      () => callback();
-      console.info('clipboard successfully set: ', newClip);
-    }, () => {
-      /* clipboard write failed */
-      console.warn('clipboard write failed');
-    });
-  }
+    _updateClipboard(newClip, callback) {
+      navigator.clipboard.writeText(newClip).then(() => {
+        /* clipboard successfully set */
+        () => callback();
+        console.info('Clipboard successfully set: ', newClip);
+      }, () => {
+        /* clipboard write failed */
+        console.warn('Clipboard write failed');
+      });
+    }
 
-  function _confirm(button, copyIcon, doneIcon) {
-    // initial opacity
-    let op = 1;
+    _confirmCopy(button, copyIcon, doneIcon) {
+      // initial opacity
+      let op = 1;
 
-    // make button visible
-    button.style.opacity = 1;
+      // make button visible
+      button.style.opacity = 1;
 
-    // make DONE icon visible (instead of default COPY)
-    copyIcon.style.display = 'none';
-    doneIcon.style.display = 'contents';
+      // make DONE icon visible (instead of default COPY)
+      copyIcon.style.display = 'none';
+      doneIcon.style.display = 'contents';
 
-    const fadeTimer = setInterval(() => {
-      if (op <= 0.1) {
-        clearInterval(fadeTimer);
+      const fadeTimer = setInterval(() => {
+        if (op <= 0.1) {
+          clearInterval(fadeTimer);
 
-        // make button invisible
-        button.style.opacity = '';
+          // make button invisible
+          button.style.opacity = '';
 
-        // make COPY icon visible back
-        copyIcon.style.display = 'contents';
-        doneIcon.style.display = 'none';
-      }
-      op -= op * 0.1;
-    }, 30);
+          // make COPY icon visible back
+          copyIcon.style.display = 'contents';
+          doneIcon.style.display = 'none';
+        }
+        op -= op * 0.1;
+      }, 30);
+    }
   }
 
+  Stimulus.application.register("copy_stable_link_button", CopyStableLinkController);
+
 })();

strictdoc/export/html/_static/stable_uri_forwarder.js

@@ -0,0 +1,85 @@
+// stable_uri_forwarder.js
+//
+// This script is included from the project's index.html page (in static HTML export)
+// It checks for a known MID or UID in the #anchor, and then
+// redirects to the referenced section or node within the project.
+// 
+// Example: 
+//   http://strictdoc.company.com/#SDOC_UG will redirect to
+//   http://strictdoc.company.com/strictdoc/docs/strictdoc_01_user_guide.html#SDOC_UG
+//
+// Thanks to this mechanism, it becomes possible to export stable links to
+// nodes/requirements/sections for integration with external tools.
+// The external links remain stable, even if the node/requirement/section is moved
+// within the project.
+
+
+// Resolve the MID / UID to the correct page / anchor using the projectMap.
+function resolveStableUriRedirectUsingProjectMap(anchor) {
+    const anchorIsMID = /^[a-fA-F0-9]{32}$/.test(anchor);
+    for (const [page, nodes] of Object.entries(projectMap)) {
+        for (const node of nodes) {
+            const nodeHasMID = 'MID' in node && typeof node['MID'] === 'string';
+            if ( (anchorIsMID && nodeHasMID && node['MID']?.toLowerCase() === anchor.toLowerCase()) 
+                || (node['UID'] === anchor)
+            )
+            {
+                window.location.replace(page + "#" + node['UID']);
+                return;
+            }
+        }        
+    }
+}
+
+// Dynamically load the projectMap an resolve MID / UID.
+function loadProjectMapAndResolveStableUriRedirect(anchor) {
+    
+    // ProjectMap is loaded, no need to load it again.
+    if (typeof projectMap !== 'undefined') {
+        resolveStableUriRedirectUsingProjectMap(anchor);
+        return;
+    }
+
+    // Get script URL and derive from it the url of project_map.js
+    const scriptUrl = new URL(document.getElementById("stable_uri_forwarder").src, window.location.href)
+    const projectMapUrl = new URL('project_map.js', scriptUrl).href;
+
+    // Dynamically load project map and resolve
+    const script = document.createElement("script");
+    script.src = projectMapUrl;
+    script.onload = () => resolveStableUriRedirectUsingProjectMap(anchor);
+    script.onerror = () => {
+        console.error(`Failed to load project map from ${projectMapUrl}`);
+    };
+    document.head.appendChild(script);
+}
+
+function processStableUriRedirect(anchor)
+{
+    const exportType = document.querySelector('meta[name="strictdoc-export-type"]')?.content;
+
+    if (exportType === 'webserver') {
+        // For the web server, we let the main_router.py dynamically forward UID to node.
+        window.location.replace("/UID/" + anchor);
+    } else if (exportType === 'static') {
+        // For static exports, we use the project_map.js.
+        loadProjectMapAndResolveStableUriRedirect(anchor)
+    }
+}
+
+
+// In case an anchor is present at content load time.
+document.addEventListener("DOMContentLoaded", () => {
+    const anchor = window.location.hash.substring(1);
+    if (anchor) {
+        processStableUriRedirect(anchor)
+    }
+});
+
+// In case an anchor is added manually afterwards (eases testing).
+window.addEventListener("hashchange", () => {
+    const anchor = window.location.hash.substring(1);
+    if (anchor) {
+        processStableUriRedirect(anchor)
+    }
+});

strictdoc/export/html/generators/project_map.py

@@ -0,0 +1,24 @@
+from markupsafe import Markup
+
+from strictdoc.core.project_config import ProjectConfig
+from strictdoc.core.traceability_index import TraceabilityIndex
+from strictdoc.export.html.generators.view_objects.project_tree_view_object import (
+    ProjectTreeViewObject,
+)
+from strictdoc.export.html.html_templates import HTMLTemplates
+
+
+class ProjectMapGenerator:
+    @staticmethod
+    def export(
+        project_config: ProjectConfig,
+        traceability_index: TraceabilityIndex,
+        html_templates: HTMLTemplates,
+    ) -> Markup:
+        assert isinstance(html_templates, HTMLTemplates)
+
+        view_object = ProjectTreeViewObject(
+            traceability_index=traceability_index,
+            project_config=project_config,
+        )
+        return view_object.render_map(html_templates.jinja_environment())

strictdoc/export/html/generators/view_objects/document_screen_view_object.py

@@ -349,10 +349,24 @@ def should_display_included_documents_for_document(
 
     def should_display_stable_link(
         self, node: Union[SDocDocument, SDocSection, SDocNode]
-    ):
+    ) -> bool:
         assert isinstance(node, (SDocDocument, SDocSection, SDocNode)), node
         return node.reserved_uid is not None
 
-    def get_stable_link(self, node: Union[SDocDocument, SDocSection, SDocNode]):
+    def get_stable_link(
+        self, node: Union[SDocDocument, SDocSection, SDocNode]
+    ) -> str:
+        """
+        An example of a link produced: ../../#SDOC_UG_CONTACT
+        The copy_stable_link_button_controller.js consumes this link and
+        transforms it into a link like:
+        http://127.0.0.1:5111/#SDOC_UG_CONTACT
+        """
+
         assert isinstance(node, (SDocDocument, SDocSection, SDocNode)), node
-        return "#TBD"
+        base_url = self.link_renderer.render_url("")
+        if node.reserved_uid is not None:
+            return base_url + "#" + node.reserved_uid
+        if node.reserved_mid is not None and node.mid_permanent:
+            return base_url + "#" + node.reserved_mid
+        return base_url

strictdoc/export/html/generators/view_objects/project_tree_view_object.py

@@ -1,6 +1,7 @@
-# mypy: disable-error-code="no-any-return,no-untyped-call,no-untyped-def"
 from dataclasses import dataclass
 
+from markupsafe import Markup
+
 from strictdoc import __version__
 from strictdoc.core.document_tree_iterator import DocumentTreeIterator
 from strictdoc.core.file_tree import File, Folder
@@ -40,18 +41,23 @@ def __init__(
             traceability_index.contains_included_documents
         )
 
-    def render_screen(self, jinja_environment: JinjaEnvironment):
+    def render_screen(self, jinja_environment: JinjaEnvironment) -> Markup:
         return jinja_environment.render_template_as_markup(
             "screens/project_index/index.jinja", view_object=self
         )
 
-    def render_static_url(self, url: str):
+    def render_map(self, jinja_environment: JinjaEnvironment) -> Markup:
+        return jinja_environment.render_template_as_markup(
+            "screens/project_index/project_map.jinja.js", view_object=self
+        )
+
+    def render_static_url(self, url: str) -> str:
         return self.link_renderer.render_static_url(url)
 
-    def render_url(self, url: str):
+    def render_url(self, url: str) -> str:
         return self.link_renderer.render_url(url)
 
-    def render_static_url_with_prefix(self, url: str):
+    def render_static_url_with_prefix(self, url: str) -> str:
         return self.link_renderer.render_static_url_with_prefix(url)
 
     def is_empty_tree(self) -> bool:

strictdoc/export/html/html_generator.py

@@ -29,6 +29,9 @@
 from strictdoc.export.html.generators.document_tree import (
     DocumentTreeHTMLGenerator,
 )
+from strictdoc.export.html.generators.project_map import (
+    ProjectMapGenerator,
+)
 from strictdoc.export.html.generators.project_statistics import (
     ProgressStatisticsGenerator,
 )
@@ -106,6 +109,9 @@ def export_complete_tree(
         # _pickle.PicklingError: Can't pickle <function sync_do_first at 0x1077bdf80>: it's not the same object as jinja2.filters.sync_do_first
         self.export_project_tree_screen(traceability_index=traceability_index)
 
+        # Export JavaScript map of the document tree (project map)
+        self.export_project_map(traceability_index=traceability_index)
+
         # Export project statistics.
         if self.project_config.is_feature_activated(
             ProjectFeature.PROJECT_STATISTICS_SCREEN
@@ -487,6 +493,25 @@ def export_project_tree_screen(
         with open(output_file, "w", encoding="utf8") as file:
             file.write(output)
 
+    def export_project_map(
+        self,
+        *,
+        traceability_index: TraceabilityIndex,
+    ):
+        assets_dir = os.path.join(
+            self.project_config.export_output_html_root,
+            self.project_config.dir_for_sdoc_assets,
+        )
+        output_file = os.path.join(assets_dir, "project_map.js")
+        writer = ProjectMapGenerator()
+        output = writer.export(
+            self.project_config,
+            traceability_index=traceability_index,
+            html_templates=self.html_templates,
+        )
+        with open(output_file, "w", encoding="utf8") as file:
+            file.write(output)
+
     def export_requirements_coverage_screen(
         self,
         *,

strictdoc/export/html/renderers/link_renderer.py

@@ -27,7 +27,7 @@ def __init__(self, *, root_path, static_path: str):
         self.local_anchor_cache = {}
         self.req_link_cache = {}
 
-    def render_url(self, url):
+    def render_url(self, url: str) -> str:
         url = html.escape(url)
         if len(self.root_path) == 0:
             return url
@@ -39,7 +39,7 @@ def render_static_url(self, url: str) -> str:
     # This rarely used helper adds slashes to the import statements within
     # <script type="module">, for example project_index/index.jinja.
     # Otherwise, scripts are not imported correctly.
-    def render_static_url_with_prefix(self, url):
+    def render_static_url_with_prefix(self, url: str) -> str:
         static_url = "/" + self.static_path + "/" + url
         return static_url
 

strictdoc/export/html/templates/base.jinja.html

@@ -5,6 +5,11 @@
   <meta charset="UTF-8"/>
   <meta name="keywords" content="strictdoc, documentation, documentation-tool, requirements-management, requirements, documentation-generator, requirement-specifications, requirements-engineering, technical-documentation, requirements-specification"/>
   <meta name="description" content="strictdoc. Software for technical documentation and requirements management."/>
+  {%- if view_object.project_config.is_running_on_server %}
+  <meta name="strictdoc-export-type" content="webserver">
+  {%- else -%}
+  <meta name="strictdoc-export-type" content="static">
+  {%- endif -%}
 
   <link rel="shortcut icon" href="{{ view_object.render_static_url('favicon.ico') }}" type="image/x-icon"/>
 

strictdoc/export/html/templates/components/node/copy_stable_link_button.jinja

@@ -1,16 +1,12 @@
 {#
-  Requires: copy_stable_link_observer.js (uses MutationObserver).
-
-  To return to using Stimulus:
-  use copy_stable_link_button_controller.js in index.jinja
-  and uncomment [data-controller] below.
+  Requires: copy_stable_link_button_controller.js in index.jinja
 #}
 {%- if path is defined -%}
   <div
     data-controller="copy_stable_link_button"
     data-path="{{ path }}"
     class="copy_stable_link-button"
-    title="Click to copy stable link to the node"
+    title="Click to copy a stable node link to the clipboard"
   >
     <span style="display: contents;" class="copy_to_clipboard-copy_icon">
       {% include "_res/svg_ico16_link.jinja" %}