Re: [PATCH RFC v2] docs: experimental: build PDF with rst2pdf

[Jonathan Corbet]

On Fri, 11 Dec 2020 09:33:32 +0100
Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> wrote:

> Add an experimental PDF builder using rst2pdf
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> 
> Please notice that 18 documents (of a total of 71) won't build with 
> rst2pdf. There's an opened issue about that at:
> 
>     https://github.com/rst2pdf/rst2pdf/issues/958
> 
> v2: usage of SPHINXDIRS was fixed.
> 
> 
>  Documentation/Makefile                     |  5 +++++
>  Documentation/conf.py                      | 21 +++++++++++++++------
>  Documentation/sphinx/load_config.py        | 12 ++++++++++++
>  Documentation/userspace-api/media/Makefile |  1 +
>  Makefile                                   |  4 ++--
>  5 files changed, 35 insertions(+), 8 deletions(-)

So I would dearly love to have rst2pdf working.

I applied this, then tried to see what would happen if I ran a build
without having rst2pdf installed:

> 1108 meer kernel: make htmldocs
>   SPHINX  htmldocs --> file:///stuff/k/git/kernel/Documentation/output
> make[2]: Nothing to be done for 'html'.
> WARNING: The kernel documentation build process
>         support for Sphinx v3.0 and above is brand new. Be prepared for
>         possible issues in the generated output.
>         enabling CJK for LaTeX builder
> 
> Extension error:
> Could not import extension rst2pdf.pdfbuilder (exception: No module named 'rst2pdf')
> make[1]: *** [Documentation/Makefile:91: htmldocs] Error 2
> make: *** [Makefile:1663: htmldocs] Error 2

Methinks it's perhaps not quite ready for linux-next yet :)

With rst2pdf installed I get a bunch of zero-length files, as promised.
Pretty much none of the larger "books" make it through.  It's a start,
though.  I'll happily apply this as a step forward once it doesn't break
the docs build if rst2pdf is missing.

Thanks,

jon