organize notebooks

[cehbrecht]

See examples:
https://github.com/ioos/notebooks_demos

[nilshempelmann]

@cehbrecht
Organisation proposition:
{bird}_{version}_{process}_{version}_{example/demo/tutorial}.ipynb

[cehbrecht]

@nilshempelmann currently the birds have all there own notebooks. So, this repo is not much used ... we might collect general examples or demos.

[nilshempelmann]

@cehbrecht: If birds have their own notebooks, the birdhouse tutorials (combining birds) should be here: https://github.com/bird-house/birdhouse-docs, right?

But general suggestion: Moving the notebooks out of the birds would reduce the datasize of the birds. For the longterm, the notebook repository should be used. Opinions?

[huard]

@nilshempelmann We're increasingly using the notebooks as integration tests. This means that with each PR, Travis-CI runs the notebooks against the server code to check that a change in the processes did not lead to a failure in the notebooks. In this sense. having the notebooks within each bird is very convenient.

The question now is how to aggregate all those notebooks at a single place in the bird-house documentation.

[nilshempelmann]

I get the idea for tests. (serverside)
For tutorials and examples (clientside) code should be easy accessable, having the low bandwidth regions in mind. Downloading a notebook can already be an obstical

[huard]

Our strategy is to collect notebooks on our own JupyterLab server.

[nilshempelmann]

Thats a good startegy. But you still keep them in the bird-repositories?

[nilshempelmann]

@huard
If I got it right, this here could be a solution to keep a documentation sync with a notebook:
https://nbsphinx.readthedocs.io/en/0.5.1/

[nilshempelmann]

@cehbrecht @huard
Checking out the notebooks of raven, I understood that shinx is converting them ... ok, ok ... got it :-)
So the place for bird notebooks is
{bird}//docs/source/notebooks/
and general tutorials:
.birdhouse-docs/docs/source/{tutorial}

This repoitory here is obsolete than... and the issue can be closed?

[huard]

One thing that remains to be done is organizing the collection of notebooks from individual birds, and thinking about integration notebooks using processes from independent bird. In PAVICS, we keep those general notebooks in pavics-sdi/docs/source/notebooks, but some of them could be moved to birdhouse. Some of them are specific to the pavics infrastructure.

[nilshempelmann]

OK, so this could be placed in this notebook-repository or in .birdhouse-docs/docs/source/

[Zeitsperre]

@nilshempelmann Should we open a PR to do this?

[nilshempelmann]

@Zeitsperre This issue is on the low burner, since the notebooks gets organized in the birds.
Here we could e.g establish and collect general tutorials.
A PR might be a bit overdosed since this repository is almost at scratch. Just push into master, finetuning can be done with a PR.