export/html: document meta information: recognize @GIT_VERSION and @GIT_BRANCH markers

Author: stanislaw

.gitignore

@@ -26,6 +26,7 @@ tests/unit_server/**/output/**
 
 ### LIT/FileCheck integration tests' artifacts. ###
 tests/integration/**/Output/**
+# This helps to gitignore fake git repositories that are created by the integration tests.
 tests/integration/**/output/**
 tests/integration/**/sandbox/
 .lit_test_times.txt

strictdoc/export/html/generators/document.py

@@ -7,6 +7,7 @@
 )
 from strictdoc.export.html.html_templates import HTMLTemplates
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
+from strictdoc.helpers.git_client import GitClient
 
 
 class DocumentHTMLGenerator:
@@ -17,6 +18,7 @@ def export(
         traceability_index,
         markup_renderer,
         link_renderer: LinkRenderer,
+        git_client: GitClient,
         standalone: bool,
         html_templates: HTMLTemplates,
     ):
@@ -27,6 +29,7 @@ def export(
             project_config=project_config,
             link_renderer=link_renderer,
             markup_renderer=markup_renderer,
+            git_client=git_client,
             standalone=standalone,
         )
         return view_object.render_screen(html_templates.jinja_environment())

strictdoc/export/html/generators/document_deep_trace.py

@@ -6,6 +6,7 @@
 )
 from strictdoc.export.html.html_templates import HTMLTemplates
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
+from strictdoc.helpers.git_client import GitClient
 
 
 class DocumentDeepTraceHTMLGenerator:
@@ -16,6 +17,7 @@ def export_deep(
         traceability_index,
         markup_renderer,
         link_renderer: LinkRenderer,
+        git_client: GitClient,
         html_templates: HTMLTemplates,
     ):
         view_object = DocumentScreenViewObject(
@@ -25,6 +27,7 @@ def export_deep(
             project_config=project_config,
             link_renderer=link_renderer,
             markup_renderer=markup_renderer,
+            git_client=git_client,
             standalone=False,
         )
         return view_object.render_screen(html_templates.jinja_environment())

strictdoc/export/html/generators/document_pdf.py

@@ -7,6 +7,7 @@
 )
 from strictdoc.export.html.html_templates import HTMLTemplates
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
+from strictdoc.helpers.git_client import GitClient
 
 
 class DocumentHTML2PDFGenerator:
@@ -17,6 +18,7 @@ def export(
         traceability_index,
         markup_renderer,
         link_renderer: LinkRenderer,
+        git_client: GitClient,
         standalone: bool,
         html_templates: HTMLTemplates,
     ):
@@ -27,6 +29,7 @@ def export(
             project_config=project_config,
             link_renderer=link_renderer,
             markup_renderer=markup_renderer,
+            git_client=git_client,
             standalone=standalone,
         )
         return view_object.render_screen(html_templates.jinja_environment())

strictdoc/export/html/generators/document_table.py

@@ -6,6 +6,7 @@
 )
 from strictdoc.export.html.html_templates import HTMLTemplates
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
+from strictdoc.helpers.git_client import GitClient
 
 
 class DocumentTableHTMLGenerator:
@@ -16,6 +17,7 @@ def export(
         traceability_index,
         markup_renderer,
         link_renderer: LinkRenderer,
+        git_client: GitClient,
         html_templates: HTMLTemplates,
     ):
         view_object = DocumentScreenViewObject(
@@ -25,6 +27,7 @@ def export(
             project_config=project_config,
             link_renderer=link_renderer,
             markup_renderer=markup_renderer,
+            git_client=git_client,
             standalone=False,
         )
         return view_object.render_screen(html_templates.jinja_environment())

strictdoc/export/html/generators/document_trace.py

@@ -6,6 +6,7 @@
 )
 from strictdoc.export.html.html_templates import HTMLTemplates
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
+from strictdoc.helpers.git_client import GitClient
 
 
 class DocumentTraceHTMLGenerator:
@@ -16,6 +17,7 @@ def export(
         traceability_index,
         markup_renderer,
         link_renderer: LinkRenderer,
+        git_client: GitClient,
         html_templates: HTMLTemplates,
     ):
         view_object = DocumentScreenViewObject(
@@ -25,6 +27,7 @@ def export(
             project_config=project_config,
             link_renderer=link_renderer,
             markup_renderer=markup_renderer,
+            git_client=git_client,
             standalone=False,
         )
         return view_object.render_screen(html_templates.jinja_environment())

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

@@ -19,6 +19,8 @@
 from strictdoc.export.html.html_templates import JinjaEnvironment
 from strictdoc.export.html.renderers.link_renderer import LinkRenderer
 from strictdoc.export.html.renderers.markup_renderer import MarkupRenderer
+from strictdoc.helpers.git_client import GitClient
+from strictdoc.helpers.string import interpolate_at_pattern_lazy
 from strictdoc.server.helpers.turbo import render_turbo_stream
 
 
@@ -33,6 +35,7 @@ def __init__(
         project_config: ProjectConfig,
         link_renderer: LinkRenderer,
         markup_renderer: MarkupRenderer,
+        git_client: GitClient,
         standalone: bool,
     ):
         self.document_type: DocumentType = document_type
@@ -42,6 +45,7 @@ def __init__(
         self.project_config: ProjectConfig = project_config
         self.link_renderer: LinkRenderer = link_renderer
         self.markup_renderer: MarkupRenderer = markup_renderer
+        self.git_client: GitClient = git_client
         self.standalone: bool = standalone
         self.document_iterator = self.traceability_index.get_document_iterator(
             self.document
@@ -190,6 +194,21 @@ def render_update_document_content_with_moved_node(
         )
         return output
 
+    def render_document_version(self) -> Optional[str]:
+        if self.document.config.version is None:
+            return None
+
+        def resolver(variable_name):
+            if variable_name == "GIT_VERSION":
+                return self.git_client.get_commit_hash()
+            elif variable_name == "GIT_BRANCH":
+                return self.git_client.get_branch()
+            return variable_name
+
+        return interpolate_at_pattern_lazy(
+            self.document.config.version, resolver
+        )
+
     def is_empty_tree(self) -> bool:
         return self.document_tree_iterator.is_empty_tree()
 

strictdoc/export/html/html_generator.py

@@ -44,6 +44,7 @@
 from strictdoc.export.html.renderers.markup_renderer import MarkupRenderer
 from strictdoc.export.html.tools.html_embedded import HTMLEmbedder
 from strictdoc.helpers.file_system import sync_dir
+from strictdoc.helpers.git_client import GitClient
 from strictdoc.helpers.paths import SDocRelativePath
 from strictdoc.helpers.timing import measure_performance
 
@@ -54,6 +55,7 @@ def __init__(
     ):
         self.project_config: ProjectConfig = project_config
         self.html_templates = html_templates
+        self.git_client: GitClient = GitClient(commit_hash=None)
 
     def export_complete_tree(
         self,
@@ -326,6 +328,7 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
+                git_client=self.git_client,
                 standalone=False,
                 html_templates=self.html_templates,
             )
@@ -346,7 +349,8 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
-                self.html_templates,
+                git_client=self.git_client,
+                html_templates=self.html_templates,
             )
             document_out_file = document_meta.get_html_table_path()
             with open(document_out_file, "w", encoding="utf8") as file:
@@ -365,7 +369,8 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
-                self.html_templates,
+                git_client=self.git_client,
+                html_templates=self.html_templates,
             )
             document_out_file = document_meta.get_html_traceability_path()
             with open(document_out_file, "w", encoding="utf8") as file:
@@ -384,7 +389,8 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
-                self.html_templates,
+                git_client=self.git_client,
+                html_templates=self.html_templates,
             )
             document_out_file = document_meta.get_html_deep_traceability_path()
             with open(document_out_file, "w", encoding="utf8") as file:
@@ -401,6 +407,7 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
+                git_client=self.git_client,
                 standalone=False,
                 html_templates=self.html_templates,
             )
@@ -418,6 +425,7 @@ def export_single_document(
                 traceability_index,
                 markup_renderer,
                 link_renderer,
+                git_client=self.git_client,
                 standalone=True,
                 html_templates=self.html_templates,
             )

strictdoc/export/html/templates/components/node_field/document_meta/index.jinja

@@ -8,10 +8,12 @@
       {%- endwith -%}
     </sdoc-meta-field>
     {%- endif -%}
-    {%- if view_object.document.config.version -%}
+
+    {% set document_version_ = view_object.render_document_version() %}
+    {%- if document_version_ is not none -%}
     <sdoc-meta-label data-testid="document-config-version-label">VERSION:</sdoc-meta-label>
     <sdoc-meta-field data-testid="document-config-version-field">
-      {%- with field_content = view_object.document.config.version %}
+      {%- with field_content = document_version_ %}
         {%- include "components/field/index.jinja" -%}
       {%- endwith -%}
     </sdoc-meta-field>

strictdoc/export/html2pdf/html2pdf_generator.py

@@ -14,6 +14,7 @@
 from strictdoc.export.html.renderers.markup_renderer import MarkupRenderer
 from strictdoc.export.html2pdf.pdf_print_driver import PDFPrintDriver
 from strictdoc.helpers.exception import StrictDocException
+from strictdoc.helpers.git_client import GitClient
 from strictdoc.helpers.timing import measure_performance
 
 
@@ -29,6 +30,8 @@ def export_tree(
         if not project_config.is_activated_html2pdf():
             raise StrictDocException("HTML2PDF feature is not enabled")
 
+        git_client: GitClient = GitClient(commit_hash=None)
+
         path_to_output_pdf_html_dir = os.path.join(output_html2pdf_root, "html")
         path_to_output_pdf_pdf_dir = os.path.join(output_html2pdf_root, "pdf")
 
@@ -64,6 +67,7 @@ def export_tree(
                     traceability_index,
                     markup_renderer,
                     link_renderer,
+                    git_client=git_client,
                     standalone=False,
                     html_templates=html_templates,
                 )

strictdoc/helpers/git_client.py

@@ -7,6 +7,7 @@
 class GitClient:
     def __init__(self, commit_hash: Optional[str]):
         self._commit_hash: Optional[str] = commit_hash
+        self._branch: Optional[str] = None
 
     @staticmethod
     def create():
@@ -26,4 +27,43 @@ def create():
         return GitClient(commit_hash=commit_hash)
 
     def get_commit_hash(self) -> Optional[str]:
+        if self._commit_hash is not None:
+            return self._commit_hash
+        try:
+            process_result = subprocess.run(
+                ["git", "describe", "--always", "--tags"],
+                cwd=os.getcwd(),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if process_result.returncode != 0:
+                return "N/A"
+            commit_hash = process_result.stdout
+        except subprocess.CalledProcessError:
+            commit_hash = "N/A"
+        except FileNotFoundError:
+            commit_hash = "Git not available"
+        self._commit_hash = commit_hash.strip()
         return self._commit_hash
+
+    def get_branch(self) -> Optional[str]:
+        if self._branch is not None:
+            return self._branch
+        try:
+            process_result = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=os.getcwd(),
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if process_result.returncode != 0:
+                return "N/A"
+            branch = process_result.stdout
+        except subprocess.CalledProcessError:
+            branch = "N/A"
+        except FileNotFoundError:
+            branch = "Git not available"
+        self._branch = branch.strip()
+        return self._branch

strictdoc/helpers/string.py

@@ -90,3 +90,13 @@ def create_safe_document_file_name(string) -> str:
 
 def ensure_newline(text: str) -> str:
     return text.rstrip() + "\n"
+
+
+def interpolate_at_pattern_lazy(template: str, value_resolver) -> str:
+    pattern = r"@(\w+)"
+
+    def replace_variable(match):
+        variable_name = match.group(1)
+        return value_resolver(variable_name)
+
+    return re.sub(pattern, replace_variable, template)