Add support for index notebooks as group overviews

[jlstevens]

examples.pyviz.org already supports having groups of notebooks under one heading such as the three attractors notebooks:

This is already great but with one small feature we could allow these groups to act as mini examples of the dedicated topics websites (e.g earthsim or earthml). In the description (e.g 'Calculate and plot 2d attractors of various types' above), it would be very nice if we could put a link on that visits an index.ipynb (or overview.ipynb or similar).

This index notebook would help provide an overview of the group and help people visit the notebooks in the group in an appropriate order. The idea is that with by adding a bit of scaffolding and context around the whole group of notebooks (which can obviously still crosslink between each other), the topic becomes more of a cohesive unit just like earthsim and earthml) (though without Tutorial and FAQ sections).

Then examples.pyviz.org can serve the purpose of presenting isolated topic notebooks, disjointed topic notebooks that are in the same domain but without any meaningful story to link them as well as more cohesive sections that someone interested in a particular domain can work through in a well defined order.

Hope that makes sense!

[jbednar]

I think this would be a useful capability.

[jsignell]

I think that the concept of "an appropriate order" doesn't really align with the notion of topics, but I don't have a strong feeling either way. I would like to note though that each of these sections represents one project at the moment. If we want to change that there will need to be some tweaking of the general structure.

[jbednar]

There is definitely an appropriate order for the Attractors notebooks; some of them explain much more than others. I'm not sure what you mean by "each of these sections"; I don't think the proposal involves having multiple projects per directory, just multiple documents per directory that then lead to the need for an index, but all with the same anaconda-project (and typically sharing a data file, etc.).

[jsignell]

But I don't think that the various topics under earthmsim or earthml share a datafile. Maybe I am misunderstanding the proposal. Is it just to add an index? Or is it to have grouping such as earthsim and earthml?

[jlstevens]

My thinking is that it would be nice to have an index per project and nothing more required.

[jsignell]

ok phew! That is fine. It might be slightly odd to special case notebooks named index.ipynb so that they don't show up in the thumbnails though. Is that what you were imagining?

[jlstevens]

Yes, I do think it should be a special case though I think it would also be ok to have a thumbnail as long as index.ipynb is always the first one shown (i.e leftmost).

[jsignell]

Would you want the others to be in the order found in the index? I think that would be kind of tricky.

[jbednar]

I think that respecting the order in the index.ipynb is indeed too tricky, as it would have to assume a very constrained format for the index.ipynb.

Note that this proposal doesn't allow us to eliminate EarthML or EarthSim; it just fills in a gap. I'm thinking of it as a continuum of project complexity like this:

1. individual .ipynb and no dependencies
2. anaconda project with one .ipynb and an environment
3. anaconda project with multiple .ipynbs and an environment
4. anaconda project with multiple ipynbs, an environment, and an index that organizes it all
5. separate github repo with arbitrarily many environments and .ipynbs and potentially its own Python module (like EarthSim and EarthML)

nbviewer and anaconda.org already handle 1, examples.pyviz.org already handles 2 and 3, and github handles 5. This proposal lets examples.pyviz.org handle case 4, i.e. somewhat bigger than case 3, but not so big that it needs its own repository, its own issue trackers, its own dedicated website, etc. It's a low-cost approximation to case 5, much more lightweight, but still sharing the property that there can be an index that organizes and explains a set of interrelated items.

[jsignell]

I have been thinking about this more since I am setting up a mechanism to allow notebooks to be skipped. Where would the index be linked from? Would it be enough to include a link to the index in the description of the project?

[jbednar]

Sure.

[jsignell]

I spoke with @jlstevens and we decided that the whole description text can be a link to the index. I've implemented that in https://github.com/pyviz-topics/examples/pull/70.

[jsignell]

Closed in #70. Adding docs soon, but should "just work" if there is a notebook named index.ipynb.