Data needed by Jupyter notebooks in GeoClaw docs

[rjleveque]

@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]

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]

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]

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

[mandli]

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]

@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]

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