HTML2PDF: Set up a good rule for splitting the node fields across multiple pages

[stanislaw]

[jenkevinwedding]

I'm encountering an issue using both the server and the command line to export PDF documentation. Using the server, I can view the html2pdf PDF output within the browser and headers/footers look correct. When I go to either save it as a PDF within Chrome or if I use chromedriver and run the export from the command line, several pages are missing headers and/or footers. It looks like this issue might already be tracking the problem, but I wanted to confirm.

Adding an illustration from the strictdoc docs below:

Good:

Bad:

[mettta]

@jenkevinwedding Thanks for the report! Could you please attach the PDF that shows the issue?

[jenkevinwedding]

Sure, I've attached the PDF file I grabbed the images from as well as the export log. I'm using version 0.11.3. It appears that the headers/footers are missing when there is a page break in the middle of a section. The .html file renders fine. I'm using Chrome 140.0.7339.128.

strictdoc_01_user_guide.html

strictdoc_01_user_guide.pdf

strictdoc-pdf-export-log.txt

[stanislaw]

@jenkevinwedding This looks like a regression, and we don't have PDF integration tests for it yet.

I have opened a ticket on the upstream project: mettta/html2pdf#129.

[mettta]

@jenkevinwedding @stanislaw I’ve added a quick workaround in Strictdoc ( #2462 ): The backgrounds of the problematic split sections are now disabled for @media print. This prevents them from overlapping the header/footer areas when exporting PDFs.
The underlying issue lies in html2pdf4doc itself and will still occur outside of Strictdoc when specific CSS styling is applied; a proper fix will be implemented upstream in a future html2pdf4doc release.

[stanislaw]

I have merged the workaround. We will release a new Pip with this fix today.

[stanislaw]

One interesting homework item is how to write an integration test that catches this properly 🤔

[mettta]

@stanislaw I added a rule to keep meta in ‘narrative’ nodes together.

But found another bug reproducible only in this Strictdoc build, cannot reproduce it in html2pdf under identical conditions.

The no-hanging directive fails for one admonition:

For Strictdoc, I'm making a fix:

as a safeguard, added .html2pdf4doc-no-break to prevent page breaks for this single admonition only.
This is a narrow workaround using existing html2pdf4doc rules.

1. added data-no-break-selectors='.html2pdf4doc-no-break ... to html2pdf4doc config in html
2. used it in RST:

.. note::
    :class: html2pdf4doc-no-break

    Composite requirements should ... (content here)

[jenkevinwedding]

Thanks for all of the comments and quick fix/workaround. I'll give it a try when released to Pip and report back.

[jenkevinwedding]

One interesting homework item is how to write an integration test that catches this properly 🤔

I have almost no knowledge of the underlying code, so this could be a terrible suggestion, but what initially comes to mind is making one of the header text fields unique in a config and then comparing the number of generated PDF document pages to the count of unique text and ensure they are equal.