Merge pull request #2235 from thseiler/feature/2229-add-metadata

export/html2pdf: #2229 additional metadata for the front page

Author: stanislaw

docs/strictdoc_01_user_guide.sdoc

@@ -812,6 +812,35 @@ Default is ``True``.
 
 [/SECTION]
 
+[SECTION]
+MID: 726b6a1a2f854e82a7670cb8480b887e
+TITLE: Additional Metadata
+
+[TEXT]
+MID: f86d45b7ad1a48ec919b43a695ca9126
+STATEMENT: >>>
+StrictDoc allows additional metadata to be added in the [DOCUMENT] element. The ``METADATA:`` field accepts any number of entries, each consisting of a key-value pair on a separate line. Keys must begin with a letter and end with a colon, but are not otherwise constrained.
+
+.. code-block:: text
+
+    [DOCUMENT]
+    TITLE: Hello world
+    OPTIONS:
+      REQUIREMENT_IN_TOC: True
+    METADATA:
+      KEY: Value
+      ...
+
+The additional metadata is also included on the front page of the exported PDF. This is useful for displaying document-specific information, such as the author's name or project identifiers.
+
+.. note ::
+
+    The front page can be further customised using the ``html2pdf_template``
+    directive in strictoc.toml
+<<<
+
+[/SECTION]
+
 [/SECTION]
 
 [SECTION]
@@ -3516,7 +3545,7 @@ To activate the HTML2PDF screen in the web interface, add/edit the ``strictdoc.t
       "HTML2PDF"
     ]
 
-This feature is not enabled by default because the implementation has not been completed yet. The underlying JavaScript library is being improved with respect to how the SDoc HTML content is split between pages, in particular the splitting of HTML ``<table>`` tags is being worked out. One feature which is still missing is the ability to generate user-specific front pages with custom meta information.
+This feature is not enabled by default because the implementation has not been completed yet. The underlying JavaScript library is being improved with respect to how the SDoc HTML content is split between pages, in particular the splitting of HTML ``<table>`` tags is being worked out. One feature which is still missing is the ability to edit custom front page metadata through the web UI.
 <<<
 
 [/SECTION]

strictdoc/backend/sdoc/grammar/grammar.py

@@ -83,6 +83,7 @@
     )?
     ('  DEFAULT_VIEW: ' default_view = SingleLineString '\n')?
   )?
+  ('METADATA:' '\n' custom_metadata = DocumentCustomMetadata)?
 ;
 
 DocumentView[noskipws]:
@@ -133,6 +134,17 @@
 LayoutChoice[noskipws]:
   'Default' | 'Website'
 ;
+
+DocumentCustomMetadata[noskipws]:
+  (entries+=DocumentCustomMetadataKeyValuePair)*
+;
+
+DocumentCustomMetadataKeyValuePair[noskipws]:
+  '  ' key=DocumentCustomMetadataKey ': ' value=SingleLineString '\n'
+;
+
+DocumentCustomMetadataKey: /[a-zA-Z_][a-zA-Z0-9_-]*/;
+
 """
 
 SECTION_GRAMMAR = rf"""

strictdoc/backend/sdoc/models/constants.py

@@ -1,6 +1,10 @@
 from strictdoc.backend.sdoc.models.anchor import Anchor
 from strictdoc.backend.sdoc.models.document import SDocDocument
-from strictdoc.backend.sdoc.models.document_config import DocumentConfig
+from strictdoc.backend.sdoc.models.document_config import (
+    DocumentConfig,
+    DocumentCustomMetadata,
+    DocumentCustomMetadataKeyValuePair,
+)
 from strictdoc.backend.sdoc.models.document_from_file import DocumentFromFile
 from strictdoc.backend.sdoc.models.document_grammar import (
     DocumentGrammar,
@@ -68,6 +72,8 @@
 
 DOCUMENT_MODELS = [
     DocumentConfig,
+    DocumentCustomMetadata,
+    DocumentCustomMetadataKeyValuePair,
     SDocDocument,
     DocumentView,
     ViewElement,

strictdoc/backend/sdoc/models/document_config.py

@@ -1,13 +1,38 @@
-# mypy: disable-error-code="no-untyped-def"
-from typing import Optional
+from typing import Dict, List, Optional
 
 from strictdoc.helpers.auto_described import auto_described
 
 
+@auto_described
+class DocumentCustomMetadataKeyValuePair:
+    def __init__(
+        self,
+        *,
+        parent: Optional["DocumentCustomMetadata"] = None,
+        key: Optional[str],
+        value: Optional[str],
+    ) -> None:
+        _ = parent
+        self.key = key
+        self.value = value
+
+
+@auto_described
+class DocumentCustomMetadata:
+    def __init__(
+        self,
+        *,
+        parent: Optional["DocumentConfig"] = None,
+        entries: Optional[List[DocumentCustomMetadataKeyValuePair]],
+    ) -> None:
+        _ = parent
+        self.entries = entries
+
+
 @auto_described
 class DocumentConfig:
     @staticmethod
-    def default_config(document) -> "DocumentConfig":
+    def default_config(document) -> "DocumentConfig":  # type: ignore[no-untyped-def]
         return DocumentConfig(
             parent=document,
             version=None,
@@ -23,9 +48,10 @@ def default_config(document) -> "DocumentConfig":
             requirement_style=None,
             requirement_in_toc=None,
             default_view=None,
+            custom_metadata=None,
         )
 
-    def __init__(
+    def __init__(  # type: ignore[no-untyped-def]
         self,
         *,
         parent,
@@ -42,6 +68,7 @@ def __init__(
         requirement_style: Optional[str],
         requirement_in_toc: Optional[str],
         default_view: Optional[str],
+        custom_metadata: Optional[DocumentCustomMetadata],
     ) -> None:
         self.parent = parent
         self.version: Optional[str] = version
@@ -84,6 +111,8 @@ def __init__(
         self.ng_line_start: int = 0
         self.ng_col_start: int = 0
 
+        self.custom_metadata: Optional[DocumentCustomMetadata] = custom_metadata
+
     def get_markup(self) -> str:
         if self.markup is None:
             return "RST"
@@ -113,7 +142,7 @@ def get_requirement_prefix(self) -> str:
             return self.requirement_prefix
         return "REQ-"
 
-    def has_meta(self):
+    def has_meta(self) -> bool:
         # TODO: When OPTIONS are not provided to a document, the self.number and
         # self.version are both None. Otherwise, they become empty strings "".
         # This issue might deserve a bug report to TextX.
@@ -124,3 +153,21 @@ def has_meta(self):
                 self.classification is not None and len(self.classification) > 0
             )
         )
+
+    def has_custom_meta(self) -> bool:
+        return (
+            self.custom_metadata is not None
+            and self.custom_metadata.entries is not None
+        )
+
+    def get_custom_meta(self) -> Optional[Dict[str, str]]:
+        if (
+            self.custom_metadata is not None
+            and self.custom_metadata.entries is not None
+        ):
+            return {
+                entry.key: entry.value
+                for entry in self.custom_metadata.entries
+                if entry.key is not None and entry.value is not None
+            }
+        return {}

strictdoc/backend/sdoc/writer.py

@@ -175,6 +175,24 @@ def write_with_fragments(
                     output += default_view
                     output += "\n"
 
+            custom_metadata = document_config.custom_metadata
+            if custom_metadata is not None:
+                output += "METADATA:"
+                output += "\n"
+
+                for keyvalue_pair in custom_metadata.entries:
+                    if (
+                        keyvalue_pair.key is not None
+                        and keyvalue_pair.value is not None
+                    ):
+                        output += (
+                            "  "
+                            + keyvalue_pair.key
+                            + ": "
+                            + keyvalue_pair.value
+                        )
+                        output += "\n"
+
         document_view = document.view
         assert len(document_view.views) > 0
         if not isinstance(document_view.views[0], DefaultViewElement):

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

@@ -1,5 +1,8 @@
-{%- if view_object.document.config.has_meta() -%}
+{%- set document_config = view_object.document.config -%}
+
+{%- if document_config.has_meta() or document_config.has_custom_meta() -%}
   <sdoc-meta>
+    {% if document_config.has_custom_meta %}
     {%- if view_object.document.config.uid -%}
     <sdoc-meta-label data-testid="document-config-uid-label">UID:</sdoc-meta-label>
     <sdoc-meta-field data-testid="document-config-uid-field">
@@ -44,5 +47,16 @@
     </sdoc-meta-field>
     {%- endif -%}
 
+    {% set custom_metadata = document_config.get_custom_meta() %}
+    {% for key, value in custom_metadata.items() %}
+    <sdoc-meta-label data-testid="document-config-version-label">{{key}}:</sdoc-meta-label>
+    <sdoc-meta-field data-testid="document-config-version-field">
+      {%- with field_content = value %}
+        <sdoc-autogen>{{ field_content }}</sdoc-autogen>
+      {%- endwith -%}
+    </sdoc-meta-field>
+    {% endfor %}
+    {% endif %}
+
   </sdoc-meta>
 {%- endif -%}

tests/end2end/screens/pdf/view_pdf_document_custom_template/document.sdoc

@@ -1,2 +1,11 @@
 [DOCUMENT]
 TITLE: Empty Document
+VERSION: Git commit: @GIT_VERSION, Git branch: @GIT_BRANCH
+DATE: @GIT_COMMIT_DATETIME
+CLASSIFICATION: Confidential
+OPTIONS:
+  REQUIREMENT_STYLE: Inline
+METADATA:
+  AUTHOR: James T. Kirk
+  CHECKED-BY: Chuck Norris
+  APPROVED-BY: Wile E. Coyote

tests/end2end/screens/pdf/view_pdf_document_custom_template/html2pdf_template/index.jinja

@@ -48,7 +48,8 @@ Notes:
     {{ view_object.document.title }}</h1>
   </div>
   <div class="html2pdf-frontpage-grid-bottom">
-{%- if view_object.document.config.has_meta() -%}
+{%- set document_config = view_object.document.config -%}
+{%- if document_config.has_meta() or document_config.has_custom_meta() -%}
   <sdoc-meta>
     {%- if view_object.document.config.uid -%}
     <sdoc-meta-label data-testid="document-config-uid-label">UID:</sdoc-meta-label>
@@ -97,6 +98,24 @@ Notes:
       {%- endwith -%}
     </sdoc-meta-field>
     {%- endif -%}
+    
+    {% if document_config.has_custom_meta %}
+    {% set custom_metadata = document_config.get_custom_meta() %}
+    {% for key, value in custom_metadata.items() %}
+    <sdoc-meta-label data-testid="document-config-version-label">{{key}}:</sdoc-meta-label>
+
+    {# We make the custom metadata fields higher with a min-height style directive.
+       We do this to support the review/release workflows at ACME laboratories inc.,
+       which involve placing "electronic signatures" on the front page of the PDF. 
+    #}
+    <sdoc-meta-field data-testid="document-config-version-field" style="min-height: 60px;">
+      {%- with field_content = value %}
+        <sdoc-autogen>{{ field_content }}</sdoc-autogen>
+      {%- endwith -%}
+    </sdoc-meta-field>
+    {% endfor %}
+    {% endif %}
+
   </sdoc-meta>
 {%- endif -%}
   </div>

tests/end2end/screens/pdf/view_pdf_document_custom_template/test_case.py

@@ -36,4 +36,12 @@ def test(self):
             screen_pdf.assert_on_pdf_document()
             screen_pdf.assert_not_empty_view()
 
+            #
+            # Check that text from the custom template is there
+            #
             screen_pdf.assert_text("ACME Laboratories Inc.")
+
+            #
+            # Check that metadata from the document is there
+            #
+            screen_pdf.assert_text("Wile E. Coyote")

tests/unit/helpers/document_builder.py

@@ -105,6 +105,7 @@ def _create_empty_document(
             requirement_style=None,
             requirement_in_toc=None,
             default_view=None,
+            custom_metadata=None,
         )
         section_contents = []
         document = SDocDocument(

tests/unit/strictdoc/backend/sdoc/test_dsl_passthrough.py

@@ -678,6 +678,31 @@ def test_073_document_config_requirement_prefix(default_project_config):
     assert input_sdoc == output
 
 
+def test_074_document_config_metadata(default_project_config):
+    input_sdoc = """
+[DOCUMENT]
+TITLE: Test Doc
+UID: SDOC-01
+VERSION: 0.0.1
+METADATA:
+  AUTHOR: James T. Kirk
+  CHECKED-BY: Chuck Norris
+  APPROVED-BY: Wile E. Coyote
+
+[REQUIREMENT]
+""".lstrip()
+
+    reader = SDReader()
+
+    document = reader.read(input_sdoc)
+    assert isinstance(document, SDocDocument)
+
+    writer = SDWriter(default_project_config)
+    output = writer.write(document)
+
+    assert input_sdoc == output
+
+
 def test_090_document_config_all_fields(default_project_config):
     input_sdoc = """
 [DOCUMENT]