Document the API

[jbarnoud]

With @HubLot work, the API starts to look like a proper API. Yet, it should be documented or it will be unusable by others.

I suggest to build the doc interactively. First we should have a reference documentation built on the docstrings, then we could add examples in the form of notebooks, finally we should add some narrative doc.

I suggest to use sphinx to generate the doc. The doc can be hosted either as github pages, using the pipy doc hosting service or using read the docs.

The course of action would be:

• [ ] set-up sphinx to build a reference doc
• [ ] clean the docstrings so they render properly
• [ ] choose a hosting service for the doc
• [ ] add example notebooks
• [ ] include the notebooks in the sphinx doc (see http://sphinx-ipynb.readthedocs.org/en/latest/howto.html)
• [ ] write narrative doc

This should be built on top of #80 or wait for #80 to be merged.

[pierrepo]

At first, I would prefer we write notebook user cases. I want to be sure the fresh API that has just been release is robust and easy-to-use.

[jbarnoud]

The steps do not have to follow a particular order. I actually started with notebooks as they are funnier to do...

[pierrepo]

;-)

[jbarnoud]

Being able to install PBxplore using a setup.py script (#21) would ease greatly the notebooks.

[HubLot]

It's on my top priority :)