linux-kernel - Re: Making pdfdocs with sphinx

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-next>] [day] [month] [year] [list]

Message-ID: <20160810120535.27570309@vela.lan>
Date:	Wed, 10 Aug 2016 12:05:35 -0300
From:	Mauro Carvalho Chehab <mchehab@...radead.org>
To:	"Luis R. Rodriguez" <mcgrof@...nel.org>
Cc:	"jani. nikula" <jani.nikula@...el.com>, linux-doc@...r.kernel.org,
	"linux-kernel@...r.kernel.org" <linux-kernel@...r.kernel.org>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Jonathan Corbet <corbet@....net>
Subject: Re: Making pdfdocs with sphinx - only select rst targets

Em Wed, 10 Aug 2016 07:42:42 -0700
"Luis R. Rodriguez" <mcgrof@...nel.org> escreveu:

> On Aug 10, 2016 1:41 AM, "Mauro Carvalho Chehab" <mchehab@...radead.org>
> wrote:
> >
> > Em Tue, 9 Aug 2016 18:19:14 -0700
> > "Luis R. Rodriguez" <mcgrof@...nel.org> escreveu:
> >  
> > > I'm excited to see the new documentation format, so I'm changing my
> > > documentation in the pending patches I have to use it. I however
> > > cannot generate anything other than the main
> > >
> > > Documentation/output/pdf/Kernel.pdf
> > >
> > > How can I see in PDF the other documentation?
> > >
> > > I'm using:
> > >
> > > make DOCBOOKS="" pdfdocs
> > >
> > > The Documentation/output/pdf/Kernel.pdf only has a bit of the
> > > documentation on how to write docs, nothing else. Using htmldocs as a
> > > target works but I am not a fan of that output.  
> >
> > Hi Luis,
> >
> > Unfortunately, on my tests with Sphinx, I noticed that pdf output is
> > not actually working fine. It relies on a tool called rst2pdf. On
> > my tests, I noticed that:
> >
> > - rst2pdf is completely broken with Sphinx 1.3.x;
> > - rst2pdf doesn't handle complex documents, even with Sphinx 1.4.5;
> > - rst2pdf always report a successful build, even when it fails;
> > - I also consulted a developer with years of experience with Sphinx: he
> >   recommended removing the media book from the pdf build, as he doesn't
> >   know any fixup or replacement for the tool that would work for the
> >   media docs.  
> 
> Hmm I see. What was the limitting issue ? The fact that media had embedded
> PDFs?

I guess not... I tried to debug rst2pdf, but it is very hard to identify
the problem, as it doesn't point where the error is. I remember I changed
some things to fix rst2pdf parser, but it still complains that some things
were missing.

> >
> > If you want to play with PDF output, you should take a look on this patch:
> >         https://patchwork.kernel.org/patch/9231687/
> >
> > (commit 520a247760f750307b53db905a10a17df1700f3b)
> >
> > Reverting it or adding your document main rst file there would let you  
> play
> > with pdfdocs, if you're using Sphinx version 1.4.x.
> >
> > If you revert it, you'll also need the enclosed patch.  
> 
> Ah OK thanks. So if our documentation works with this and PDF output we can
> add just that single doc (in my case a new folder), is that right ?

Not sure. Better ask Jon how he wants to proceed with that.

Regards,
Mauro