Fix docs PDF build about gammapy HOT 12 CLOSED

It looks like a PDF was generated yesterday on readthedocs at
https://media.readthedocs.org/pdf/gammapy/latest/gammapy.pdf
whick looks mostly OK.

I've copied it here for future reference:
https://dl.dropboxusercontent.com/u/4923986/gammapy/gammapy.pdf

Currently the PDF build on readthedocs doesn't work for unknown reasons:
readthedocs/readthedocs.org#894

from gammapy.

@eteq @astrofrog I'm having trouble getting the Gammapy PDF build to work ... if you have any idea how to resolve these errors, that would be much appreciated.

I'm using these commands

python setup.py install
cd docs
make latex
make pdflatex

Full log: https://gist.github.com/cdeil/b55a18481e990e0cf129

make latex works, but then make pdflatex gives two errors from Sphinx references ... see two examples below.

LaTeX Warning: Hyper reference `references:lima1983' on page 13 undefined on in
put line 339.

See log here ... this originates from the reference [LiMa1983]_ in https://github.com/gammapy/gammapy/blob/master/docs/introduction.rst which does work in html and is expanded to the latex {\hyperref[references:lima1983]{{[}LiMa1983{]}}}.

LaTeX Warning: Hyper reference `api/gammapy.spectrum.crab_flux:gammapy.spectrum
.crab_flux' on page 13 undefined on input line 352.

See log here ... this originates from the reference

`~gammapy.spectrum.crab_flux`

in https://github.com/gammapy/gammapy/blob/master/docs/introduction.rst which does work in html and is expanded to the latex {\hyperref[api/gammapy.spectrum.crab_flux:gammapy.spectrum.crab_flux]{\code{crab\_flux}}}.

I've tested this a bit with Astropy itself and the package-template and it works and I can't figure out what the problem is in Gammapy!?

from gammapy.

@cdeil - I'm really not sure because I've not worried too much about the latex docs. But on the LiMa reference, is there anything different about how there nearby Meyer2010 reference is expanded? It seems like it should be exactly the same...

from gammapy.

I looked at this again for the upcoming Gammapy 0.3 release.

Well, at some point (no idea when) the Gammapy PDF build on readthedocs started working again:
https://readthedocs.org/builds/gammapy/3176162/
The PDF looks OK.

I tried to build the PDF on my Macbook.

As described here in the Astropy docs, the proper commands to build the PDF are:

python setup.py build_sphinx -b latex
cd docs/_build/latex
pdflatex gammapy

At first I got an error from pdflatex that inconsolata.sty is missing, but as noted in the Astropy-docs, installing texlive-fonts-extra fixed it:

sudo port install texlive-fonts-extra

Then the PDF build fails with this error:
https://gist.github.com/cdeil/d10c858692aa902ffa4c#file-gistfile1-txt-L1250

It's pointing to this line in the Sphinx-generated gammapy.tex:
https://gist.github.com/cdeil/470f03224b4df3f53c08#file-gistfile1-txt-L3057

So it looks like there's a formatting issue with this table (which looks OK in the html output)
http://gammapy.readthedocs.org/en/latest/dataformats/file_formats.html#overview

The readthedocs log doesn't show what commands they run, so I don't know why it works there.
So for now I'll keep this issue open, but move the milestone to the 0.4 release.

from gammapy.

The PDF build is currently working locally for me and on RTD.

The PDF looks mostly OK:
https://media.readthedocs.org/pdf/gammapy/latest/gammapy.pdf

500 pages, and I didn't even know we had so many pretty Figures.

I've added the commands that work for me locally to build the PDF in #714 (commit: 0274c03)

Closing this issue now.

from gammapy.

Gammapy PDF build is broken again on RTD:
http://readthedocs.org/projects/gammapy/builds/4649893/

Re-opening this issue.

• Fix PDF build
• Add PDF docs build on travis-ci so that this doesn't keep breaking

from gammapy.

@bsipocz - Thanks for making the PR #779.

The Gammapy PDF docs build has been braking many times over the past years.

Would it be possible to add a travis-ci build that runs it?
I think the commands that should be run are these and then the exit status needs to be checked:
http://docs.gammapy.org/en/latest/development/howto.html#sphinx-docs-build

python setup.py build_docs -b latex
cd docs/_build/latex
makeindex -s python.ist gammapy.idx
pdflatex -interaction=nonstopmode gammapy.tex

from gammapy.

PDF is currently working: https://media.readthedocs.org/pdf/gammapy/latest/gammapy.pdf
Remaining task is stated in my last comment: add CI build for PDF to make sure it doesn't break again.
Moving this issue to v0.7.

from gammapy.

I'm closing this old issue now. At the moment, we don't offer a PDF or EPUB version of the Gammapy docs any more. It would only be of interest to a small fraction of users, most use HTML. Maybe it still works, I didn't try. I'd suggest to just do nothing here. There are other features for docs that IMO would be more important, e.g. a version chooser for the HTML docs.

from gammapy.

@cdeil - with RTD there should be an option to choose the version (though with quick look it seems that you don't use that on http://docs.gammapy.org/?)

from gammapy.

@cdeil
The main problem with version switching is in the Tutorial part.

• How to get the right notebooks for an old version?
• Do we propose to download old notebooks?
• How to make old version notebooks work in Binder?

from gammapy.

@Bultako - I realise multi-version selector isn't easy to implement.

We already discussed a bit in #1241 .

Let's not continue here, but over there, but with low priority, only if someone has time to work on this.

from gammapy.