Hi all,
I just wanted to mention some upcoming things that should make the experience of using and learning Bokeh even better, as well as to point out some tools we created that might be of wider interest. First I wanted to point you to this PR:
document all models completely by bryevdv · Pull Request #1759 · bokeh/bokeh · GitHub
The goal of this PR is to have **complete automated reference documentation for 100% of Bokeh models**. This includes all the properties, their types (with links) and docstrings. A JSON serialization prototype in a collapsible div, and (eventually) an inline example plot where applicable (see below about the new bokeh-plot:: directive). Most of this work is done; you can see the WIP version of the docs here:
bokeh.models — Bokeh 2.3.3rc1 Documentation
Obviously there are still lots of other gaps to fill in, but I believe that a fully complete automated reference is be the first, necessary step towards truly exceptional documentation. Even if you are using higher level APIs, it is ultimately always Bokeh models that are always created, so a reference for these should help everyone out. For the upcoming 0.8 release in February, we do plan to add more content to the User's Guide as well. The bokeh plot directive will make adding live examples in the User's Guide much better and easier. Please take a look, any feedback on what you think is missing or most needs improvement would be very valuable.
To make these improvements possible, we became intimately familiar with writing Sphinx extensions. Most of these are probably not that interesting to normal users. But there are two that might be of general interest. The first is a "collapsible" code block that works with the sphinx bootstrap theme:
bokeh.sphinxext — Bokeh 2.3.3rc1 Documentation
The second is a bokeh plot directive that lets you include Bokeh plots directly in your Sphinx docs, either with the code inline in the directive, or loaded from an external file:
bokeh.sphinxext — Bokeh 2.3.3rc1 Documentation
We used this to greatly simplify and streamline the generation of the main gallery. With this in place, we plan to expand and split up the gallery into more logical sections, as well as automate indexing and cross-referencing, etc.
We are also in the process of updating and improving some of our build processes. Soon, every "dev build" that we release with come with the proper BokehJS available on CDN as well as a corresponding docs snapshot deployed to the pydata site.
Hopefully all these things will make it as easy as possible to find all the up-to-date information you need to use Bokeh. But please head over to GitHub to let us know what else needs improvement, or to pitch in and help!
Thanks,
Bryan
Continuum Analytics