Documentation structure overhaul

[PeterDSteinberg]

• See how Holoviews uses notebooks that are tested automatically to fill out code and output examples in the documentation. Coordinate with @jbednar on the details of how that works. We have too many code snippets in Elm's docs to maintain currently. Aim to remove code snippets expressed in the ./docs folder (somehow get it automatically from notebook cells + add CI testing to those notebooks). May involve making new notebooks.
  • The outputs of cells should be tracked so you can do assertions
  • Get the documentation snippets tested somehow on each push / Travis test
• We also need doctests in the source code - not enough there now (delay this work ~1.5 months)
• We also have plan the messaging around earthio + xarray_filters as experimental repos and how to get help there or find help ...? Should help for all these be in one place (the current readthedocs)? Phased implementation towards 2 to 3 separate docs sites that link to each other?

Order of operations:

• Copy the scaffolding of the notebook testing / docs system of Holoviews - customize as necessary (can start this immediately)
• Content edits - regarding the interactions of repos (the docs are now all elm-based with little description about the point of Earthio / xarray_filters and not much help on those either). Approx date for this is: Sept 15, 2017
• Content edits - regarding refactored usage: Oct 1, 2017 or earlier

[PeterDSteinberg]

cc @gbrener Ideas?

[jbednar]

Copy the scaffolding of the notebook testing / docs system of Holoviews - customize as necessary (can start this immediately)

Yes and no! Our scaffolding is amazing and also hellish. We have agreed on a plan to make it portable between projects, but we don't have time to start that plan yet until we can deliver on one of our client projects that has a milestone approaching. I agree that it's urgent to get this sort of stuff in place for elm (as it is for datashader), but is there any way this could be delayed by 1 month? If so we'll be able to clean it up, separate it into a useful system, and then start using it widely.

[gpfreitas]

@PeterDSteinberg I'll wait for your answer to @jbednar's question.

In the meantime, can someone explain at a high level the pros/cons of the way Bokeh does documentation (traditional Sphinx, from what I can see) vs the way that holoviews does?

[PeterDSteinberg]

Delaying for a month sounds good @jbednar @gpfreitas . I'll label this issue as deferred.

[jbednar]

In the meantime, can someone explain at a high level the pros/cons of the way Bokeh does documentation (traditional Sphinx, from what I can see) vs the way that holoviews does?

The HoloViews website is actually based on the Bokeh docs infrastructure, but it extends it to build the site nearly entirely from notebooks rather than from .rst, to automate various additional aspects of the gallery when building from notebooks, to add automatic cross-linking between notebooks (so that the notebooks link to .ipynb files but when deployed as a web site the links go to the deployed .htmls), and to allow automatic testing of notebook outputs.

The result is that writing and maintaining the website becomes nearly entirely a matter of writing notebooks and putting them into a certain directory structure, which is good because those same notebooks are then available to the users to re-run and compare their results, and then use them as starting points. Everything then stays up to date automatically as long as you maintain the notebooks, in principle (once we finish up some key sticky points).

We may be able to move the "month away" time forward; we have yet another project that needs a website, and so we are meeting on Monday to see if there's any way we can get this functionality published as a viable separate tool earlier.

[PeterDSteinberg]

@gpfreitas is working on documentation in xarray_filters

[PeterDSteinberg]

See notes on issue #185 regarding documentation needs related to Elm PR #192's changes for evolutionary search.

[PeterDSteinberg]

Docstrings are absent or insufficient in these places (and likely others):

• elm.pipeline.steps - See @gpfreitas 's work in xarray_filters for wrapping the docstring of an underlying wrapped function (xarray_filters.datasets) and do the same kind of thing for elm.pipeline.steps wrapping the docs of the sklearn estimator that is the ._cls attribute of an elm.pipeline.steps class like elm.pipeline.steps.linear_model.LinearRegression and including a note that the wrapping of that sklearn class is intended for use with xarray_filters.MLDataset / xarray.Dataset.

[PeterDSteinberg]

cc @hsparra