Merge pull request #2610 from strictdoc-project/stanislaw/html2pdf_forced_break

feat(html2pdf): introduce a new "html2pdf_forced_page_break_nodes" option

Author: stanislaw

docs/strictdoc_01_user_guide.sdoc

@@ -3419,7 +3419,7 @@ MID: 225dc4d22c084a67ae049fca1098bc1a
 STATEMENT: >>>
 StrictDoc uses an internal default template when exporting documents in PDF format.
 
-If the front page, header, or footer needs to be customised, it is possible to provide a custom template with the `html2pdf_template` option.
+If the front page, header, or footer needs to be customised, it is possible to provide a custom template with the ``html2pdf_template`` option.
 
 .. code:: toml
 
@@ -4085,6 +4085,36 @@ To activate the HTML2PDF screen in the web interface, add/edit the ``strictdoc.t
 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.
 <<<
 
+[[SECTION]]
+MID: 2f3f0488d9564d43a7fdb6f071b1cae9
+TITLE: Forcing a page break for each node
+
+[TEXT]
+MID: 202f6fffba9f4000a95cd69933839fc3
+STATEMENT: >>>
+The ``html2pdf_forced_page_break_nodes`` allows specifying which nodes should always start on a new page when printed to PDF using the HTML2PDF feature. It is especially useful for documents that contain very large, descriptive requirement nodes with a lot of text. In such cases, starting each node on a new page helps avoid having the beginning of a node lost in the middle of a page.
+
+Example of ``strictdoc_config.py``:
+
+.. code-block:: py
+
+    from strictdoc.core.project_config import ProjectConfig
+
+
+    def create_config() -> ProjectConfig:
+        config = ProjectConfig(
+            project_features=[
+                "HTML2PDF",
+            ],
+            html2pdf_forced_page_break_nodes=[
+                "REQUIREMENT"
+            ]
+        )
+        return config
+<<<
+
+[[/SECTION]]
+
 [[/SECTION]]
 
 [[SECTION]]

docs/strictdoc_04_release_notes.sdoc

@@ -66,6 +66,8 @@ Also, a Pygments lexer for the SDoc markup has been added to the StrictDoc sourc
     IMPORT_FROM_FILE: @my_grammar
 
 Thanks to @gregshue for requesting this feature and explaining the need for it.
+
+3\) Based on a user report, the ``html2pdf_forced_page_break_nodes`` option has been added to the StrictDoc configuration. This option allows specifying which nodes should always start on a new page when printed to PDF using the HTML2PDF feature. It is especially useful for documents that contain very large, descriptive requirement nodes with a lot of text. In such cases, starting each node on a new page helps avoid having the beginning of a node lost in the middle of a page. Thanks to @xw-mk for the clear request.
 <<<
 
 [[/SECTION]]

strictdoc/core/project_config.py

@@ -122,6 +122,7 @@ def __init__(
         source_nodes: Optional[List[SourceNodesEntry]] = None,
         html2pdf_strict: bool = False,
         html2pdf_template: Optional[str] = None,
+        html2pdf_forced_page_break_nodes: Optional[List[str]] = None,
         bundle_document_version: Optional[
             str
         ] = ProjectConfigDefault.DEFAULT_BUNDLE_DOCUMENT_VERSION,
@@ -230,6 +231,14 @@ def __init__(
 
         self.html2pdf_strict: bool = html2pdf_strict
         self.html2pdf_template: Optional[str] = html2pdf_template
+
+        if html2pdf_forced_page_break_nodes is not None:
+            assert isinstance(html2pdf_forced_page_break_nodes, list)
+            assert len(html2pdf_forced_page_break_nodes) <= 10
+        self.html2pdf_forced_page_break_nodes: List[str] = (
+            html2pdf_forced_page_break_nodes or []
+        )
+
         self.bundle_document_version: Optional[str] = bundle_document_version
         self.bundle_document_date: Optional[str] = bundle_document_date
 

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

@@ -431,16 +431,20 @@ def get_html2pdf_classes(self, node: SDocNode) -> str:
 
         assert isinstance(node, SDocNode), node
 
-        if not node.has_multiline_fields():
-            html2pdf4doc_classes = []
+        html2pdf4doc_classes = []
+
+        if (
+            node.node_type
+            in self.project_config.html2pdf_forced_page_break_nodes
+        ):
+            html2pdf4doc_classes.append("sdoc-html2pdf4doc-break-before")
 
+        if not node.has_multiline_fields():
             if node.get_requirement_style_mode() == "narrative":
                 html2pdf4doc_classes.append("html2pdf4doc-no-break")
 
             # The section that does not break away from its children.
             if node.has_child_nodes():
                 html2pdf4doc_classes.append("html2pdf4doc-no-hanging")
 
-            return "".join(html2pdf4doc_classes)
-
-        return ""
+        return " ".join(html2pdf4doc_classes)

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

@@ -3,16 +3,16 @@
 {% set node_type_string = sdoc_entity.get_node_type_string() %}
 
   <sdoc-node
+    class="{{ view_object.get_html2pdf_classes(sdoc_entity) }}"
     node-style="readonly"
     node-role="{{ sdoc_entity.get_type_string() }}"
     {%- if node_type_string is not none %}
       show-node-type-name="{{ node_type_string }}"
     {%- endif %}
     {# FIXME: Is this template always called on SDocNode? Can this check be removed? #}
-    {% if sdoc_entity.is_requirement() %}
+    {% if sdoc_entity.is_requirement() -%}
       node-view="{{ sdoc_entity.get_requirement_style_mode() }}"
-    {%- endif -%}
-    class="{{ view_object.get_html2pdf_classes(sdoc_entity) }}"
+    {% endif -%}
     data-testid="node-{{ sdoc_entity.get_type_string() }}"
   >
 

strictdoc/export/html/templates/screens/document/pdf/index.jinja

@@ -31,7 +31,7 @@
     data-preloader-background='#F2F5F9'
     data-forced-page-break-selectors=''
     data-page-break-after-selectors='.pdf-toc .free_text'
-    data-page-break-before-selectors='H2'
+    data-page-break-before-selectors='H2 .sdoc-html2pdf4doc-break-before'
     data-no-break-selectors='.html2pdf4doc-no-break sdoc-section-title sdoc-meta sdoc-node-title .pdf-toc-row'
     data-no-hanging-selectors='.html2pdf4doc-no-hanging sdoc-section-title sdoc-anchor sdoc-meta .admonition-title sdoc-node-title sdoc-node-field-label strong:only-child'
   src="{{ view_object.render_static_url('html2pdf4doc.min.js') }}"></script>

strictdoc_config.py

@@ -70,7 +70,8 @@ def create_config() -> ProjectConfig:
             "reports/tests_integration.lit.junit.xml": "tests/integration",
             "reports/tests_integration_html2pdf.lit.junit.xml": "tests/integration",
         },
-        html2pdf_strict=True,
+        # Waiting for a fix to be released soon.
+        html2pdf_strict=False,
         reqif_multiline_is_xhtml=True,
         reqif_enable_mid=True,
         section_behavior="[[SECTION]]",

tests/integration/features/html2pdf/08_three_requirements_each_on_new_page/input.sdoc

@@ -0,0 +1,63 @@
+[DOCUMENT]
+MID: 82becec5ace54321b135ed27d5a73c76
+TITLE: Dummy Software Requirements Specification #1
+OPTIONS:
+  ENABLE_MID: True
+
+[GRAMMAR]
+ELEMENTS:
+- TAG: TEXT
+  FIELDS:
+  - TITLE: MID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: STATEMENT
+    TYPE: String
+    REQUIRED: True
+- TAG: REQUIREMENT
+  FIELDS:
+  - TITLE: MID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: UID
+    TYPE: String
+    REQUIRED: False
+  - TITLE: TITLE
+    TYPE: String
+    REQUIRED: False
+  - TITLE: STATEMENT
+    TYPE: String
+    REQUIRED: False
+  RELATIONS:
+  - TYPE: Parent
+  - TYPE: File
+
+[REQUIREMENT]
+MID: c165cc52af20417e9199e30a4e17f138
+UID: REQ-1
+TITLE: Dummy high-level requirement #1
+STATEMENT: System ABC shall do 1.
+RELATIONS:
+- TYPE: File
+  VALUE: file.py
+
+[REQUIREMENT]
+MID: 74dddc4c55ac44ae83dc0f73ef8ed2aa
+UID: REQ-2
+TITLE: Dummy high-level requirement #2
+STATEMENT: System ABC shall do 2.
+RELATIONS:
+- TYPE: File
+  VALUE: file.py
+
+[REQUIREMENT]
+MID: fcbce0c486ac4d3189a7aa1dd646399e
+UID: REQ-3
+TITLE: Dummy high-level requirement #3
+STATEMENT: System ABC shall do 3.
+RELATIONS:
+- TYPE: File
+  VALUE: file.py

tests/integration/features/html2pdf/08_three_requirements_each_on_new_page/strictdoc_config.py

@@ -0,0 +1,13 @@
+from strictdoc.core.project_config import ProjectConfig
+
+
+def create_config() -> ProjectConfig:
+    config = ProjectConfig(
+        project_features=[
+            "HTML2PDF",
+        ],
+        html2pdf_forced_page_break_nodes=[
+            "REQUIREMENT"
+        ]
+    )
+    return config

tests/integration/features/html2pdf/08_three_requirements_each_on_new_page/test.itest

@@ -0,0 +1,19 @@
+# @relation(SDOC-SRS-51, scope=file)
+
+REQUIRES: TEST_HTML2PDF
+
+RUN: %strictdoc export %S --formats=html2pdf --output-dir %T | filecheck %s --dump-input=fail
+CHECK: html2pdf4doc: JS logs from the print session
+
+RUN: %check_exists --file %T/html2pdf/pdf/input.pdf
+
+RUN: %check_exists --file %T/html2pdf/html/%THIS_TEST_FOLDER/input-PDF.html
+RUN: cat %T/html2pdf/html/%THIS_TEST_FOLDER/input-PDF.html | filecheck %s --check-prefix=CHECK-HTML-PDF
+CHECK-HTML-PDF:     {{<sdoc-node$}}
+CHECK-HTML-PDF-NEXT:class="sdoc-html2pdf4doc-break-before"
+CHECK-HTML-PDF:     {{<sdoc-node$}}
+CHECK-HTML-PDF-NEXT:class="sdoc-html2pdf4doc-break-before"
+CHECK-HTML-PDF:     {{<sdoc-node$}}
+CHECK-HTML-PDF-NEXT:class="sdoc-html2pdf4doc-break-before"
+
+RUN: python %S/test_pdf.py