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

[Mauro Carvalho Chehab]

Em Fri, 11 Dec 2020 13:48:59 -0700
Jonathan Corbet <corbet@xxxxxxx> escreveu:

> 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 :)

Well, I haven't test this.

I'm not an usual python programmer, so, don't know much about its 
specifics... Yet, I would be expecting that something like this:

	try:
	    extensions.append("rst2pdf.pdfbuilder")
	except:
	    sys.stderr.write('rst2pdf extension not available.\n')
	

Would avoid it to crash, if the extension is not available.
Silly me :-)

Still, I suspect that it should not be hard to modify the above to
avoid the crash. 

I shouldn't be doing much development those days, as I'm taking
some vacations, after sending media stuff for 5.11. 

So, if you have a better idea about how to optionally probe an
extension, feel free to modify my patch.


> With rst2pdf installed I get a bunch of zero-length files, as promised.
> Pretty much none of the larger "books" make it through.  

Yeah. I guess one of the issues is with tables that don't fit into
a single page.

Yet, devicetree book is empty. That sounds really weird, as there are
few files on it, and I didn't see anything uncommon on the rst files.

> 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.

Sounds like a plan.

Thanks,
Mauro