961398 - Let rst2pdf build the PDF documentation if pdflatex is not available

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Frédéric Buclin]

texlive-texmf size is 1.1Gb. That's HUGE! Way too big for me to install just to generate a PDF from time to time. Instead, we should use rst2pdf, which is way smaller. With all its dependencies, it requires less than 50Mb. Much better! And the output is pretty good.

Comment 1

[Gervase Markham [:gerv]]

I like the idea of reducing the size of the deps :-) Can you attach a sample PDF from rst2pdf? Is it packaged for many OSes?

Gerv

Comment 2

[Gervase Markham [:gerv]]

Remember also that our official PDFs are going to be generated by ReadTheDocs using the texlive-texmf method, so we may want to keep both.

My suspicion is that as devs we will almost never generate the PDFs, unless someone reports a bug with the generation, which is unlikely, because Sphinx is well tested. We'll just let RTD do it for us.

Gerv

Comment 3

[Frédéric Buclin]

Attachment: patch, v1

If pdflatex is installed, use it, else fall back to rst2pdf.

I use the File::Which module which is not part of the perl core distribution and so may not be installed on your machine. But it's a popular module, so maybe it's already installed. If that's a problem, I can easily copy File::Which::which() into Bugzilla::Util as it's a very small module which has no dependencies outside core Perl modules.

You will notice that the PDF file generated by rst2pdf has not section numbering. That's due to rst2pdf not understanding :numbered:, see https://code.google.com/p/rst2pdf/issues/detail?id=392.

Comment 4

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #1)
> I like the idea of reducing the size of the deps :-) Can you attach a sample
> PDF from rst2pdf? Is it packaged for many OSes?

It's available on Windows and several Linux distros:

http://pkgs.org/search/?keyword=rst2pdf&search_on=name

Comment 5

[Frédéric Buclin]

Attachment: Bugzilla.pdf generated by rst2pdf

The PDF file matches very closely the HTML style.

Comment 6

[Gervase Markham [:gerv]]

Comment on attachment 8362173 [details] [diff] [review]
patch, v1

Unfortunately, this patch gives errors if rst2pdf is not installed :-(

If we can fix that, it looks good to me. The output's not as nice but, as you say, the dependencies are much lighter.

Who do we think would use this, though, given that anyone can just get a nice PDF from ReadTheDocs?

Gerv

Comment 7

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #6)
> Unfortunately, this patch gives errors if rst2pdf is not installed :-(

Yeah, I'm going to fix that. Thanks for catching that.


> Who do we think would use this, though, given that anyone can just get a
> nice PDF from ReadTheDocs?

Those customizing their doc to match their needs, and devs when reviewing changes in the documentation.

About being nice or not, I personally prefer the shiny colorful PDF generated by rst2pdf than this coldish PDF generated by RTD. So it's a question of taste. :)

Comment 8

[Frédéric Buclin]

Attachment: patch, v2

Now load rst2pdf conditionally.

Comment 9

[Gervase Markham [:gerv]]

Comment on attachment 8362606 [details] [diff] [review]
patch, v2

r=gerv.

Gerv

Comment 10

[Frédéric Buclin]

Committing to: bzr+ssh://[e-mail]/bugzilla/trunk/
modified docs/makedocs.pl
modified docs/en/Makefile
modified docs/en/make.bat
modified docs/en/rst/conf.py
modified docs/en/rst/index.rst
Committed revision 8878.