Documentation¶

Install requirements¶

In order to build the docs from source, you should have followed the instructions in Getting Set Up.

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.

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, first navigate to the sphinx subdirectory of the Bokeh source tree.

cd sphinx

Sphinx uses the make tool to control the build process. The most common targets or the Bokeh makefile are:

clean

Remove all previously built documentation output. All outputs will be generated from scratch on the next build.

html

Build any HTML output that is not built, or needs re-building (e.g. because the input source file has changed since the last build)

serve

Start a server to serve the docs open a web browser to display. Note that due to the JavaScript files involved, starting a real server is necessary to view many portions of the docs fully.

For example, clean the docs build directory, run the follow command at the command line:

make clean

Multiple targets may be combined in a single make invocation. For instance, executing the following command will clean the docs build, generate all HTML docs from scratch, then open a browser to display the results:

make clean html serve

By default, built docs will load the most recent BokehJS from CDN. If you are making local changes to the BokehJS and wish to have the docs use your locally built BokehJS instead, you can set the environment variable BOKEH_DOCS_CDN before calling make:

BOKEH_DOCS_CDN=local make clean html 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. (GOOD)

"""

over the more verbose sentence below:

""" This function creates and returns a new Foo. (BAD)

"""

Docstrings for functions and methods should generally include the following sections:

• Args (unless the function takes no arguments)

• Returns (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”.

A complete example might look like:

def somefunc(name, level):
    ''' Create and return a new Foo.

    Args:
        name (str) :
            A name for the Foo

        level (int) :
            A level for the Foo to be configured for

    Returns:
        Foo

    '''

Models and Properties¶

Bokeh’s Model system supports its own system for providing detailed documentation for individual properties. These are given as a help argument to the property type, which is interpreted as standard Sphinx ReST when the reference documentation is built. For example:

class DataRange(Range):
    ''' A base class for all data range types.

    '''

    names = List(String, help="""
    A list of names to query for. If set, only renderers that
    have a matching value for their ``name`` attribute will be used
    for autoranging.
    """)

    renderers = List(Instance(Renderer), help="""
    An explicit list of renderers to autorange against. If unset,
    defaults to all renderers on a plot.
    """)

Section Headings¶

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

Top level
=========

This will add a "Top Level" entry in the navigation sidebar

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

This may add a sub-entry in the sidebar, depending on configuration.

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

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

Note that the length of the underline must match that of the heading text, or else the Sphinx build will fail.

Release Notes¶

Each release should add a new file under sphinx/source/docs/releases that briefly describes the changes in the release including any migration notes. The filename should be <version>.rst, for example sphinx/source/docs/releases/0.12.7.rst. The Sphinx build will automatically add this content to the list of all releases.