improve documentation

fixes #1391

and add improvements/fixes to documentation
I would also suggest listing the interfaces in a bulleted list, definition style, to give them some visual space of their own. Regarding the names, descriptions, here is my suggestion:

* **Objects** - A low level interface that mirrors BokehJS. "some assembly required" 
* **Glyphs** - A general purpose plotting interface centered around associating data with visual glyphs
* **Charts** - A high level interface for schematic statistical charting. Easily generate well-knows chart types from a wide range of input formats.