Update usage documentation

[mrocklin]

The usage documentation seems to have gone somewhat stale. It recommends a variety of scripts rather than the nbsite executable (which seems to be recommended from within those scripts in TODO statements). I've been trying to give this a shot, have gotten as far as

nbsite init
nbsite generate-rst --examples . --project-name "Dask Examples"

However I still have questions like the following:

1. Is there a way to pre-run my notebooks automatically?
2. How do I build HTML docs after I have the rst
3. (presumably more will come after that)

Any help would be welcome

[jbednar]

Yes, it's definitely stale. Yes, there is a way to run the notebooks automatically; e.g. Panel is built automatically on a git tag. See https://github.com/pyviz/panel/blob/master/.travis.yml for the setup for that particular project. Unfortunately, we have dozens of projects and none is yet truly in the form that is intended. Panel is the most recent of those, but isn't necessarily fully set up because it's not released yet. (And its website is still quite incomplete!)

[ceball]

I apologize for the state in which you've found the documentation. Yes, it's out of date and incomplete, which is ironic given what this project is about :(

Quick excuse... The priority so far has been using this tool for sites we ourselves have needed (http://pyviz.org, http://datashader.org, http://geoviews.org, https://hvplot.pyviz.org, https://earthsim.pyviz.org, etc). Meanwhile, I'm slowly adding a more reasonable interface to make nbsite simpler to use, and it's that I want to document rather than the current horrible interface - but the new interface isn't finished yet. Hence no announcement of this project, and it's still at some early 0.something version.

I'll try to outline the steps for you here and also answer your questions. Before you spend more time, though, you should know:

• It's not yet straightforward to style nbsite-generated sites, so you'll end up with something that looks like one of the above example sites.
• The less your project folder structure looks like "the standard pyviz structure" (which I'll describe below), the less chance nbsite will work (i.e. it ought to work with a different structure, but may not have been tested yet).
• The less your project uses pyviz-related tools for visualization (e.g. holoviews), the less chance visualizations/widgets will work.
• The project really is a work in progress, so you'll surely encounter problems and confusion.

Travis files for the above-mentioned sites show the steps required to build those sites. However, the travis files are in various states of migration, including towards using a simpler nbsite interface, so they are not easy to follow :( Probably the simplest right now is https://github.com/ioam/param/blob/master/.travis.yml#L132, which shows nbsite in use to generate a simple site, https://ioam-docs.github.io/param-dev/index.html.

The result of nbsite init followed by editing of doc/conf.py has already been committed to the repository, but all the other steps are there:

1. Generate rst files in ./doc based on notebooks in ./examples: nbsite generate-rst --org ioam --project-name param --repo param --examples=./examples --doc=./doc . (The repository information is because e.g. links are generated to download the notebooks from github.)

2. (optional, probably best to skip this to start with) Generate API docs: mkdir doc/Reference_Manual && nbsite_generate_modules.py param -d ./doc/Reference_Manual -n param -e tests

3. Build the html and put in ./builtdocs; includes running the notebooks, unless they have already been run by a previous execution and haven't changed: nbsite build --what=html --examples=examples --doc=doc --output=builtdocs --examples-assets='' .

That should be it - you should be able to run something like python -m http.server from builtdocs/html. The other steps after that in the .travis file don't necessarily need to be run; they are for removing some files (e.g. the executed notebooks) and making the site work with github pages.

The typical/expected 'pyviz' structure is something like:

• project/doc - generated by nbsite init, then manually edit conf.py.
• project/examples/index.ipynb - root/homepage
• project/examples/assets - any images etc used by the notebooks (and the notebooks refer to such assets using a relative path)
• project/examples/User_Guide/index.ipynb - contents page for User Guide
• project/examples/User_Guide/01_Some_Notebook.ipynb
• project/examples/User_Guide/02_Another_Notebook.ipynb (etc)

There can be multiple collections of notebooks, e.g. project/examples/User_Guide, project/examples/Tutorial, etc (see the various projects mentioned earlier). If notebooks are named like 01_The_Notebook.ipynb, 02_Another_Notebook.ipynb, they'll appear in that order in the side navigation bar. Their titles will be taken from the filenames, though this can be overridden by editing the generated rst (and whether to skip some initial cells, e.g. a cell containing a title, can be specified).

[jbednar]

The less your project uses pyviz-related tools for visualization (e.g. holoviews), the less chance visualizations/widgets will work.

Note that Bokeh plots are "pyviz-related" whether or not they were generated with holoviews, and at least when I've tested them the various Dask visualization tools have been fine on the nbsite-generated website (e.g. http://datashader.org/topics/osm.html).

[bmorris3]

Is it possible to get an update on this comment for the latest nbsite?