-
Notifications
You must be signed in to change notification settings - Fork 195
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Integrate tutorial notebooks in Sphinx documentation #1176
Conversation
@Bultako - Thanks! I think for now, it might be easier to script the copy of the files from Line 178 in cf93c4b
Of course, yes, long term I would like to have an option for Is there some way to run the build to get "verbose" or "debug" output about what My suggestion would be that you do this first, to avoid having to have the notebooks in the The other thing that's needed to make this PR "mergeable" is to squash the merge commits and commits that contain the large notebook files: If you're not sure how to do this with git, let me know. This explanation is pretty good: One more thing on your TODO list:
I think really it would be better to change I'll have a closer look at this tomorrow. |
29eda29
to
e062134
Compare
I've fixed a few more notebook formatting issues in @Bultako - Could you please add Locally I see the following warnings from the Sphinx build: Do you know if there is a way to use the line number information in these warnings somehow to find the problematic notebook cell / line that needs to be fixed?
|
Is the plan that notebooks will be copied to Line 51 in 98c62a2
|
My last comment with the warnings at https://gist.github.com/cdeil/23072fba2afeb652b2427bda787e06ee was incorrect: I think the warnings like
should be fixed now. I just didn't realise I was running on an old version of the notebooks because |
I think the plan is still copying notebooks from $GAMMAPY_EXTRA to docs/notebooks. |
e4bd3b0
to
3b7fad0
Compare
Generated doc files added just for inspection Generated html doc removed Modif YAML files and Makefile clean notebooks Remove notebooks and examples Delete gammapy.css.~LOCAL Update .gitignore
60dce57
to
e73de44
Compare
Locally I still get these warnings:
The CI build hasn't started ... the main goal for this PR would be to get green light there: @Bultako - Do you have time to work on this PR in the coming days or is this ready to be merged from your side? I would prefer to merge this soon to see if it works on RTD, and to move the task list from above to a follow-up issue / pull request. |
2697c37
to
92c593f
Compare
I think we were working in different versions of gammapy-extra
There is a broken link in that nb, I have fixed and rebuild the docs, this time I had no warnings.. Re: Travis CI green light. We can merge this PR as it is when we'll have green light, next week I'll be a bit busy. |
Merging now. I want to do some more changes on this, but let's see if this is working on RTD at all. |
It worked! 🎉 The build log is at http://readthedocs.org/projects/gammapy/builds/6156543/, and the timeout is a weird bug in the RTD docker infrastructure - all of our builds end in a timeout, even if it was successful. So for now one has to look through the log and see if there's any error, which in this case there isn't. |
good :) |
I tried this and it finds an entry: Do you have an example search URL you're using to test? Let me try and wipe RTD to trigger a clean build now and see if that makes it better. |
I've wiped RTD and triggered a new build here: https://readthedocs.org/projects/gammapy/builds/6162287/ @Bultako - Do you have an RTD account? If yes, I would be happy to give you admin permissions there for Gammapy. |
@cdeil I've just created my |
After some investigation I've found RTD always build an HTML version together with a JSON version of the docs. These are used for web serving & search indexing, respectively. But, our last builds in RTD have not finished properly, so I suspect JSON format has not been built properly, as it is also the case with htmlzip, epub and pdf formats. Note that the You said you could have look at the build logs in RTD? |
Main modifs are:
docs/folder
(these will be copied from GAMMAPY-EXTRA later on)docs
to makenbconfig
work nicelydocs
and some *.py files ingammany
source code folder to replace directive.. code::
by..code :: python
and make code inclusion in docs working.Remember you need to install
nbsphinx
:conda install -c conda-forge nbsphinx
And that's all for the moment.
Just type
python setup.py build-docs
and this mixed interlinked doc of *rst files and notebooks is generated in one shot. We still have some warnings due to orphans *.ipynb files, but this does not prevent their conversion.This is the firs step, still work in progress..
TODO
toctree::
directiveScriptting
docs/notebooks
folder_static
folder_static
folder.