Build a viable pipeline for writing documentation.

[pbugnion]

This package desperately needs documentation. Unfortunately, the obvious solution of writing IPython notebooks and exporting them to HTML doesn't work. Javascript widgets are not included in the exported HTML, so you can't actually see the maps (see this, for instance).

I think that the solution will be to write a custom 'nbexport' script, but that sounds like a real pain.

[pbugnion]

I think the way to do this is as follows:

• write all the documentation in IPython notebooks.
• find ways of exporting the Python models to Backbone JS models. This should be as simple as defining a Jinja2 template.
• for cells corresponding to map views, export the Python model to a JS file. Add a line in the cell metadata corresponding to this JS file..
• Overload the relevant bits of nbconvert so that the JS models are embedded by default in the output of the relevant cells.
• Write contributors documentation on "how to write documentation". (How meta is that?)

This sounds like a somewhat difficult pipeline, but I think it's quite elegant. And the ability to export Python models to Backbone is an added bonus.

[pbugnion]

This is old and outdated. Closing as not really relevant.