Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Finish integration of Jupyter notebooks with Sphinx docs #1215
see generated doc:
@Bultako - Thanks!
The main thing before this can go in is that the docs build in our CI has to be green.
One suggestion I have would be to move the code you've added to
The problem with putting more and more code in
I'll have a closer look now and leave some inline comments.
@Bultako - I've left a few inline comments.
I like how you've introduced the info box at the top with a download link for the notebook!
I have a few suggestions that I think would make it more intuitive for users:
For the "download notebook" link, I think it would be great to change to "Download notebook: nbfile.ipynb" and to just have the "nbfile.ipynb" be the link. This would IMO make it more intuitive for users which file they will download and then will have to look for locally to execute. I also think it would be good to add the filenames to every notebook linked to from this page: http://docs.gammapy.org/en/latest/notebooks.html#notebooks again because people will have to know the filenames of the notebooks to start executing them and recognise them.
Finally, on nbviewer (e.g. https://nbviewer.jupyter.org/github/gammapy/gammapy-extra/blob/master/notebooks/cta_1dc_introduction.ipynb) in the top right corner there's two more useful links: one to the notebook on Github (i.e. the file someone would have to edit if they wanted to contribute) and one called "view as code" that is just a text file that people could copy & paste from into a Python script. Both of those aren't essential, but if they are easy to do, I think it would be useful to have.
@Bultako - The big extra feature would be if people could execute the examples on Binder. Axel and I tried quite a bit in the past, but mostly failed to get it to run properly. If you are interested to add it, please have a look at #726 and comment there if you want to try setting it up again for Gammapy. (Let's keep that separate from this PR, to avoid it getting very large or stalled).
@Bultako - Locally I always see these three warnings on
This is on a clean gammapy git checkout - it shouldn't have anything to do with me having old build files lying around. I don't understand why these warnings appear for me, but not on travis-ci (see https://travis-ci.org/gammapy/gammapy/jobs/305233458).
My gammapy-extra is at fe9daa9b59d97570175b85803bc0bf2d11037260 which is up-to-date as of today: https://github.com/gammapy/gammapy-extra/commits/master
I really don't understand this. The only thing I can think of are version differences between my machine (e.g. in nbconvert)!?
conda-forge provides an older version that does not handle links with RST files properly
just for info:
missing a shared docker container for reproducibility.
@Bultako - This looks very good!
I've put some minor code suggestions inline.
The download links look great now:
Source files: astropy_introduction.ipynb | astropy_introduction.py
Currently clicking the links doesn't download a file, but opens up the file as text in the browser. Would it be possible and preferable to have the default behaviour on click be a download? I'm not sure it's possible, but with this or by putting a raw HTML a tag with download attribute like this it might.
Alternatively: maybe add something like this on the line below:
(to download the files to your local machine: right-click and select "save as")
I don't know how to do this. The point is that
For the moment I've just added the message right-click and select "save as"