rst2pdf crashes with several documents from the Linux Kernel

Trying to build pdf docs from Linux .rst files doesn’t work.

Description of problem

Cloning this tree, which contains a patch adding rst2pdf support:

https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst2pdf-v3

and building the documentation with:

   $ git clone git://linuxtv.org/mchehab/experimental.git -b rst2pdf-v3
   $ make rst2pdf

Should create 71 pdf files under Documentation/output/pdf directory. 18 of them have zero size, because rst2pdf crashed.

This is an example of one of such crashes.

[ERROR] pdfbuilder.py:159 Failed to build doc
Traceback (most recent call last):
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/rst2pdf/pdfbuilder.py", line 156, in write
    docwriter.write(doctree, destination)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/rst2pdf/pdfbuilder.py", line 672, in translate
    createpdf.RstToPdf(
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/rst2pdf/createpdf.py", line 659, in createPdf
    pdfdoc.multiBuild(elements)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/platypus/doctemplate.py", line 1177, in multiBuild
    self.canv.save()
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfgen/canvas.py", line 1277, in save
    self._doc.SaveToFile(self._filename, self)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 219, in SaveToFile
    data = self.GetPDFData(canvas)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 245, in GetPDFData
    return self.format()
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 427, in format
    IOf = IO.format(self)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 876, in format
    fcontent = format(self.content, document, toplevel=1)   # yes this is at top level
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
    f = element.format(document)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 1613, in format
    return D.format(document)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 683, in format
    L = [(format(PDFName(k),document)+b" "+format(dict[k],document)) for k in keys]
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 683, in <listcomp>
    L = [(format(PDFName(k),document)+b" "+format(dict[k],document)) for k in keys]
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 80, in format
    f = element.format(document)
  File "/devel/v4l/docs/sphinx_2.4.4/lib64/python3.9/site-packages/reportlab/pdfbase/pdfdoc.py", line 1778, in format
    if f is None: raise ValueError("format not resolved, probably missing URL scheme or undefined destination target for '%s'" % self.name)
ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'sleeping-things'

🖥 Versions

$ python -V
Python 3.9.0
$ pip freeze | grep -E '(rst2pdf|reportlab|[Ss]phinx)'
reportlab==3.5.56
rst2pdf==0.98
Sphinx==2.4.4
sphinx-rtd-theme==0.5.0
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==1.0.3
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.4

Tested on Fedora 33.

[nfraprado]

I finally got around to testing if the table fix from #967 worked for the kernel docs and indeed it did! The document for the block/ subsystem which would previously fail, now is successfully generated. I attached the resulting pdf here in case anyone is curious:

block.pdf

And here’s the web version for reference.

And indeed I don’t see any issues with the tables (there are some fluctuations to the right margin, but it’s also like that on the web, so must be something with the .rst file or Sphinx itself). It seems rst2pdf did the job quite well! (I forgot to mention that there are a few warnings because the tables are too wide: [WARNING] flowables.py:862 BoundByWidth too wide to fit in frame (642.0 > 510.444094488189): <BoundByWidth at 0x7fe021333a60> containing: ['<XXPreformatted at 0x7fe021333e50>']. But in any case, the visual result is good)

Now, I think it’s only #966 left to go, which was breaking the docs of a lot of subsystems (RCU, networking, GPU, userspace-api and a few others)

[nfraprado]

Actually the issue isn’t with kernel-figure, but figure in general, and I opened an issue for that at #966.

I think if #965 gets merged, and #964, #966 and #967 get fixed, all Linux Kernel doc errors will be solved. Here’s hoping.