On 17/02/2024 22:29, Jonathan Corbet wrote:
So, FYI, I have Vegard's PDF-generation fix applied here, but I've not pushed it yet (even though I think it's fine) because I wanted to be sure that all was well with PDF generation. Bear with me as I ramble for a bit...
This won't help with the immediate issue at hand, but I am trying to put together something of a "docs CI" system that can pick up mailing list patches and do builds against all the various OS/Sphinx/target combinations. At least that was my takeaway from the recent couple of regressions I introduced: I need (much) better tests than just running 'make htmldocs' once or twice in my native environment.
I'm surprised that nobody else is reporting this problem. I honestly don't see a fix other than changing the organization of the document to avoid both deeply nested itemized lists and section structure, which is less than entirely desirable. I think there are good reasons for avoiding structures that deep, but limitations in the tooling aren't one of them.
I don't know. Tooling limitations notwithstanding, the good reasons are still there. HTML has no <h7> and that was clearly a "human" decision, not a technological limit. I think the "bug" here is really that Sphinx generated LaTeX code that doesn't build -- and that it didn't warn about the problem in other modes (maybe it does in newer versions, or maybe we overlooked the warnings?). If we'd had those warnings then we could have stopped those constructs from entering the documentation sources to start with.
Meanwhile, I wish I knew what to do to make the PDF build a bit more robust. I wish that rst2pdf or rinohtype would progress to the point where they could be used, and Latex could be taken out of the picture, but no such luck.
We could maybe use the ".. only::" directive to "#ifdef out" the parts that don't work with various output formats and then incrementally work towards removing them while ensuring that the whole build still succeeds. Vegard
