pdf output for Sphinx

pdf output for Sphinx

[Nicolas Dechesne]

hi there,

I just tried for the first time building a PDF from the Sphinx docs..
it's not bad at all.. Of course it's *different* from what we used to
have. In the previous docs system, each 'manual' was its own
standalone 'book' or project, so we had one 'web page' and one 'pdf'
for each manual or book.

The approach we decided to follow with Sphinx, is that we have one
docs project that includes all our document files (books/manual,...).

Then, obviously, when we generate a PDF output from Sphinx, we get a
single PDF file with the project's entire documentation, instead of
many PDF files.

Just running make latexpdf into the docs folder generated this PDF file:

https://people.linaro.org/~nicolas.dechesne/theyoctoproject.pdf

It's a 7MB file, with ~800 pages.. My very first impression is that it
looks really good, and to be honest, having all docs in a single file
might even be better, from a user perspective.. If you open with a PDF
viewer, you should see the 'outline' that looks like our 'left menu'
on the website, you can search any term...

I have done no customization at all, I am sure we can customize the
header/footer and improve a few things..

I had a very large number of warnings during the build, which I have
ignored for now ;)

I also ran "make latexpdf" in the bitbake docs..:
https://people.linaro.org/~nicolas.dechesne/bitbake.pdf

Feedback?

nico

Re: [docs] pdf output for Sphinx

[Richard Purdie]

On Fri, 2020-11-13 at 09:31 +0100, Nicolas Dechesne wrote:
> I just tried for the first time building a PDF from the Sphinx docs..
> it's not bad at all.. Of course it's *different* from what we used to
> have. In the previous docs system, each 'manual' was its own
> standalone 'book' or project, so we had one 'web page' and one 'pdf'
> for each manual or book.
> 
> The approach we decided to follow with Sphinx, is that we have one
> docs project that includes all our document files (books/manual,...).
> 
> Then, obviously, when we generate a PDF output from Sphinx, we get a
> single PDF file with the project's entire documentation, instead of
> many PDF files.
> 
> Just running make latexpdf into the docs folder generated this PDF
> file:
> 
> https://people.linaro.org/~nicolas.dechesne/theyoctoproject.pdf
> 
> It's a 7MB file, with ~800 pages.. My very first impression is that
> it looks really good, and to be honest, having all docs in a single
> file might even be better, from a user perspective.. If you open with
> a PDF viewer, you should see the 'outline' that looks like our 'left
> menu' on the website, you can search any term...
> 
> I have done no customization at all, I am sure we can customize the
> header/footer and improve a few things..
> 
> I had a very large number of warnings during the build, which I have
> ignored for now ;)
> 
> I also ran "make latexpdf" in the bitbake docs..:
> https://people.linaro.org/~nicolas.dechesne/bitbake.pdf
> 
> Feedback?

I think it looks good, I like it. We should start generating and
publishing them.

I was thinking we may want to publish pdfs of the individual manuals
too. I suspect that may be possible with a little creative juggling of
the files but I know how much you love my crazy scripting around things
like this! ;-) 

I'm torn on whether need to or not. 7MB for 800 pages is good going.

Cheers,

Richard

Re: [docs] pdf output for Sphinx

[Paul Barker]

On Fri, 13 Nov 2020 at 08:32, Nicolas Dechesne
<nicolas.dechesne@linaro.org> wrote:
>
> hi there,
>
> I just tried for the first time building a PDF from the Sphinx docs..
> it's not bad at all.. Of course it's *different* from what we used to
> have. In the previous docs system, each 'manual' was its own
> standalone 'book' or project, so we had one 'web page' and one 'pdf'
> for each manual or book.
>
> The approach we decided to follow with Sphinx, is that we have one
> docs project that includes all our document files (books/manual,...).
>
> Then, obviously, when we generate a PDF output from Sphinx, we get a
> single PDF file with the project's entire documentation, instead of
> many PDF files.
>
> Just running make latexpdf into the docs folder generated this PDF file:
>
> https://people.linaro.org/~nicolas.dechesne/theyoctoproject.pdf
>
> It's a 7MB file, with ~800 pages.. My very first impression is that it
> looks really good, and to be honest, having all docs in a single file
> might even be better, from a user perspective.. If you open with a PDF
> viewer, you should see the 'outline' that looks like our 'left menu'
> on the website, you can search any term...

Looks good, patch incoming to fix the TOC and outline depths....

-- 
Paul Barker
Konsulko Group

Re: [docs] pdf output for Sphinx

[Nicolas Dechesne]

On Fri, Nov 13, 2020 at 10:35 AM Richard Purdie
<richard.purdie@linuxfoundation.org> wrote:
>
> On Fri, 2020-11-13 at 09:31 +0100, Nicolas Dechesne wrote:
> > I just tried for the first time building a PDF from the Sphinx docs..
> > it's not bad at all.. Of course it's *different* from what we used to
> > have. In the previous docs system, each 'manual' was its own
> > standalone 'book' or project, so we had one 'web page' and one 'pdf'
> > for each manual or book.
> >
> > The approach we decided to follow with Sphinx, is that we have one
> > docs project that includes all our document files (books/manual,...).
> >
> > Then, obviously, when we generate a PDF output from Sphinx, we get a
> > single PDF file with the project's entire documentation, instead of
> > many PDF files.
> >
> > Just running make latexpdf into the docs folder generated this PDF
> > file:
> >
> > https://people.linaro.org/~nicolas.dechesne/theyoctoproject.pdf
> >
> > It's a 7MB file, with ~800 pages.. My very first impression is that
> > it looks really good, and to be honest, having all docs in a single
> > file might even be better, from a user perspective.. If you open with
> > a PDF viewer, you should see the 'outline' that looks like our 'left
> > menu' on the website, you can search any term...
> >
> > I have done no customization at all, I am sure we can customize the
> > header/footer and improve a few things..
> >
> > I had a very large number of warnings during the build, which I have
> > ignored for now ;)
> >
> > I also ran "make latexpdf" in the bitbake docs..:
> > https://people.linaro.org/~nicolas.dechesne/bitbake.pdf
> >
> > Feedback?
>
> I think it looks good, I like it. We should start generating and
> publishing them.

We need to play with the pdf theme/option first (a logo on the first page, ...)

>
> I was thinking we may want to publish pdfs of the individual manuals
> too. I suspect that may be possible with a little creative juggling of
> the files but I know how much you love my crazy scripting around things
> like this! ;-)
>
> I'm torn on whether need to or not. 7MB for 800 pages is good going.

I think it expects one entry page (e.g. index.rst) per PDF doc. so we
could tweak that a bit indeed. We would need to override index.rst to
generate each 'book'. But cross reference between 'book' would become
HTTP links (to docs.yp.org). With a single book, you can follow cross
references within the 'big manual'. If you search for Bitbake terms in
the current PDF, you will see they are links to bitbake html docs.
That kind of goes against the idea of having the PDF as a local copy.
In fact I would argue whether we should include the bitbake manual in
the same PDF :)

>
> Cheers,
>
> Richard
>
>
>

Re: [docs] pdf output for Sphinx

[Robert Berger]

Hi,

My comments are in-line

On 13/11/2020 10:31, Nicolas Dechesne wrote:
> 
> Feedback?

This looks pretty nice.

With the old style stuff I created pdf books with html -> latex -> pdf, 
which was quite some pain.

After a quick check the only thing I would maybe change is the size of 
some images, since they seem to be scaled by width. At least in latex 
they could be scaled to be a bit smaller, no idea how this is done with 
sphinx.

e.g. p.56 Package Splitting

> 
> nico

Regards,

Robert

> 
> 
> 
> 
>