Offer PDF of documentation

[EliL]

It could be helpful to offer the documentation as a pdf. It is not hard to create that pdf from sphinx for example 2.4 (although I've not examined it in detail for quality):

cd /usr/local/src/geomoose/geomoose2/branches/geomoose-2.4/sphinx-docs/
make latex

cd build/latex/
make all-pdf

[theduckylittle]

The main problem with this right now is that the geomoose.org server is running Debian Lenny. We can no longer install from packages and installing tex-live from source does not sound like a good way to spend the weekend.

[jimk]

Done. Although we should probably look at the docs and reorganize/tweak them to make more sense on paper as well as the web format.

http://www.geomoose.org/trunk/GeoMOOSE.pdf

[EliL]

This is 19 pages and lacks the main part of the documentation. Trunk builds this ways since r575. I'll see if I can find anything in various revisions to find the cause. I'm not exactly sure why 2.4 builds to 79 pages and includes what looks like everything, looks like we might have duplicate references and TOC issues.

[EliL]

Actually, trunk builds this way since r498. It built fine (mostly) previously.

[jimk]

r921 r922

Fixed major problems with toc lists and references as well as reorganized overall toc so the documentation also makes sense in a paper format. The PDF version is up from 19 pages to 131 pages.

http://www.geomoose.org/trunk/GeoMOOSE.pdf

[EliL]

Reorganization is an improvement for both paper and web. PDF looks good as well. Content-wise, I think that I can close this ticket.

However, when I try and build the docs myself (Ubuntu 10.04), I get an error, specifically I need to revert r922. Normally I would just commit build error fixes but since you specifically did the exact opposite I won't. I will try to ssh in to see how it works on the server and either fix my system or make another suggestion that suits both (obviously successful build on the server is the primary focus). Testing continues.

[jimk]

Replying to EliL:

However, when I try and build the docs myself (Ubuntu 10.04), I get an error, specifically I need to revert r922. Normally I would just commit build error fixes but since you specifically did the exact opposite I won't. I will try to ssh in to see how it works on the server and either fix my system or make another suggestion that suits both (obviously successful build on the server is the primary focus). Testing continues.

That's odd. I did most of the work on Ubuntu 11.04 and r921 built normally. r922 was needed to build on the server, but I don't remember testing it on my machine. My gut say r921 feels more correct (includes relative to where file that contains the include line is located) and is more consistent with the rest of the code. r921 on the server failed because it was looking for why_abstract.txt in sphinx-docs/source instead of sphinx-docs/source/info

Further testing:
On my Debian 6.0.6 box, with sphinx 0.6.6 r921 works, and r922 fails (produces no output).

source/info/why_text.txt:1: (SEVERE/4) Problems with "include" directive path:
IOError: [Errno 2] No such file or directory: '/info/why_abstract.txt'.

On my Ubuntu 11.04 box, with sphinx 1.0.1 it builds with r921 or r922 (with the same HTML/LaTeX output).

On the server Debian 6.0.? with sphinx 1.1.3 (from easy_install), r921 fails and r922 builds (HTML same, LaTeX missing a paragraph with r921).

source/info/why_text.txt:1: SEVERE: Problems with "include" directive path:
IOError: [Errno 2] No such file or directory: 'source/why_abstract.txt'.

[EliL]

I was getting the same error (SEVERE/4) with r922.

More info about 10.04 with sphinx 0.6.4-1: now builds (html and pdf) with the following change:

-.. include:: /info/why_abstract.txt
+.. include:: ./why_abstract.txt

Can you test that on your systems?

[jimk]

Replying to EliL:

I was getting the same error (SEVERE/4) with r922.

More info about 10.04 with sphinx 0.6.4-1: now builds (html and pdf) with the following change:

-.. include:: /info/why_abstract.txt
+.. include:: ./why_abstract.txt

Can you test that on your systems?

That works the same as

include:: why_abstract.txt

for me.

BTW: Sphinx 1.1.3 from easy_install (in a virtualenv) behaves the same as the server does for me on my Ubuntu machine.

I think the "problem" is how sphinx is treating nested includes.

HTML:
welcome.txt->info/why_abstract.txt
welcome.txt->info/why.txt->info/why_text.txt->info/why_abstract.txt

LaTeX:
welcome.txt->info/why_text.txt->info/why_abstract.txt

BTW: all this silliness is because for the print version it makes sense to have the full "Why GeoMOOSE" section inline, but for the web version it just has the abstract and links off to the full document.

In old sphinx it seems to be including relative to the previous file. In 1.1.3 it seems to be including relative to the first file. I wonder which one is "correct"?

​http://docutils.sourceforge.net/docs/ref/rst/directives.html#include reads to me that the relative to the including document behavior of older sphinx versions is "correct".

[EliL]

Returning from the build diversion, yes this is good. How do we want to produce this file (i.e. manually at release or cron)? Where will the url(s) be? Depending on those decisions, I'll update the release process if needed, and make references to it elsewhere in the documentation - perhaps an "offline documentation" section and download link to the pdf, here, ​http://geomoose.org/trunk/docs/index.html#

I don't particularly see a need to update the pdf more often than releases since the point of it is to print or have offline (which probably means that you won't get a new one everyday).

[jimk]

It is already being built hourly with the HTML documentation. For 2.4 and trunk it lives at http://www.geomoose.org/2.4/GeoMOOSE.pdf and http://www.geomoose.org/trunk/GeoMOOSE.pdf.

Personally, I have a lot of PDFs that I never print out, so I see no need to artificially restrict updates other than changes to branches will likely be rare (as changes to branches HTML docs are rare).

[EliL]

I was unable to guess the current release url. Neither ​http://geomoose.org/2.6.0/GeoMOOSE.pdf nor ​http://geomoose.org/GeoMOOSE.pdf worked as I expected.

[jimk]

I think that is because automatic doc building is broken for 2.6.0 (not related to PDF). There is a line in update_docs.sh to build /srv/geomoose/current which doesn't exist. I'm not sure what that line was meant to do.

[bfischer]

JimK and BrianF discussed and seems to be fixed and done. If there are further issues with the server configuration, please open new ticket and put categorize as server config.

[EliL]

added a link to actually download the (trunk) pdf, r956.