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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20201212005435.0e1a0871@coco.lan>
Date:   Sat, 12 Dec 2020 00:54:35 +0100
From:   Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Masahiro Yamada <masahiroy@...nel.org>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Michal Marek <michal.lkml@...kovi.net>,
        linux-kbuild@...r.kernel.org, linux-kernel@...r.kernel.org,
        linux-media@...r.kernel.org
Subject: Re: [PATCH RFC v2] docs: experimental: build PDF with rst2pdf

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

> On Fri, 11 Dec 2020 09:33:32 +0100
> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> 
> > Add an experimental PDF builder using rst2pdf
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> > ---
> > 
> > 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