Documentation¶

Install requirements¶

The following requirements are necessary for building Bokeh documentation:

• sphinx
• pyyaml
• packaging
• pygments

Install these requirements:

conda install -c bokeh sphinx pyyaml packaging pygments

We recommend using conda to install these requirements. Alternatively, you may use pip or install from the packages’ source.

Supported Output Formats¶

The innate dependency of Bokeh on JavaScript means that attempting other formats besides HTML cannot not produce good or usable results. Only HTML output is supported.

Install the sample data¶

Some of the Bokeh examples in the documentation rely on sample data that is not included in the Bokeh GitHub repository or released packages, due to their size.

First, make sure that the Bokeh package is installed. Install the latest development version of Bokeh, if needed:

conda install -c bokeh/channel/dev bokeh

Once Bokeh is installed, the sample data can be obtained by executing the following command at a Bash or Windows prompt:

bokeh sampledata

See Sample Data for alternative instructions on how to download the sample data.

Build the Documentation¶

To generate the full documentation, execute the following command from the sphinx subdirectory of the Bokeh source’s root directory:

cd sphinx
make clean all

Serve and Review the Documentation¶

Next to start a server and automatically open the documentation in a browser, enter:

make serve

Docstrings¶

We use Sphinx Napoleon to process docstrings for our reference documentation.

All docstrings are Google Style Docstrings. Docstrings should generally begin with a verb stating what the function or method does in a short statement. For example, the “verb first” style is preferred:

""" Create and return a new Foo."""

over the more verbose sentence below:

""" This function creates and returns a new Foo. """

Docstrings for functions and methods should include:

• Args: section (if any arguments are accepted)
• Returns: section (even if the function just returns None)

Short descriptions for parameters should be written in such a way that inserting an implicit “IS” makes a complete sentence. For example:

title_font (str, optional) : a font used for the plot title (default: Sans)

can be reasonably read as “title_font IS a font used for the plot title”.

Document headings¶

In narrative documentation, headings help the users follow the key points and sections. The following outlines the headings hierarchy:

Top level (makes a top-level entry in the side-bar)
===================================================

Second level
------------

Third level
~~~~~~~~~~~

Fourth level
''''''''''''

Note that the length of the underline should match that of the heading text.