search

clawpack / doc

General Clawpack documentation and main wiki pages
Other
13 stars 23 forks source link

Data needed by Jupyter notebooks in GeoClaw docs #164

Open rjleveque opened 7 years ago

rjleveque commented 7 years ago

@ketch, @mandli: We moved notebooks like dtopotools_examples.ipynb from the apps repository to doc/doc/geoclaw/ now that they are used in creating Sphinx documents. This avoids having multiple versions.

But we neglected to copy over the data subdirectory that is used in this notebook, so if someone downloads this notebook they won't be able to run it. More generally, even if we put data in doc/doc/geoclaw/ it's won't be clear to people going from the docs to Github that this directory is also needed, and they would have to clone the docs repository to get everything most easily.

I suggest we find a way to keep notebooks in the apps repository if they are useful enough that someone might want to download and run them. Then write a script that executes the notebook and puts the executed notebook in the 'doc' repository for processing by Sphinx, and also adds some text at the top that tells the reader that it was auto-generated from a notebook in the apps repository and directs the reader to clone that repository if they want to run the notebook.

I'll give this a shot if there are no objections.

ketch commented 7 years ago

That sounds good to me. I do think it may be fine to keep some useful notebooks that people might download and run in the docs (only) if the notebook is standalone.

It might be fine to just manually put a link to the apps version of the notebook in the notebook (manually), since then anybody who finds it anywhere will know where to get the data. Of course, the danger is that the link might break.

mandli commented 7 years ago

We could add them as a sub-repository so they could be in both places. This would require that they be branched off into their own repository though.

ketch commented 7 years ago

Just my opinion: a sub-repository for each of these may be more trouble than it's worth.

mandli commented 7 years ago

Concur on that one :)

Randy's idea of having a script copy these over seems like the best approach given that most will not need to deal with the docs repository.

rjleveque commented 7 years ago

@ketch, @mandli: I refactored a bit and now the notebooks from the apps repo are converted to html files in the doc/gallery/_static/notebooks directory. I've only implemented this for the geoclaw notebooks so far, results can be viewed at http://www.clawpack.org/gallery/notebooks.html

rjleveque commented 7 years ago

BTW, conversion is done by this script: https://github.com/clawpack/doc/blob/master/gallery/notebooks/make_html_from_notebooks.py