Re: Making pdfdocs with sphinx - only select rst targets

[Mauro Carvalho Chehab <mchehab@infradead.org>]

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

> On Aug 10, 2016 1:41 AM, "Mauro Carvalho Chehab" <mchehab@infradead.org>
> wrote:
> >
> > Em Tue, 9 Aug 2016 18:19:14 -0700
> > "Luis R. Rodriguez" <mcgrof@kernel.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