The Bokeh documentation is an important resource for the entire Bokeh
community. It helps guide new users, and it is the definitive reference for
seasoned users and developers. That is why all contributions to Bokeh must
contain adequate documentation. It is also why we have set standards to ensure
that Bokeh’s documentation remains easily accessible and up to date.
Just like Bokeh itself, the documentation is a community effort. And just like
Bokeh, the documentation is being adapted and improved all the time. In fact,
helping with the documentation is one of the most valuable ways to contribute
to Bokeh. It’s also a good way to get started and introduce yourself as a new
An easy way to get started is to submit pull requests for any typos or other
small errors you might find in Bokeh’s documentation. This is always
appreciated! In addition to quick fixes, check the list of Open Docs
Issues on GitHub. This list contains several projects as a starting
This section describes Bokeh’s
documentation style guidelines
for contributing to the documentation. This section also includes details on how
to build and
edit the documentation in your local
Bokeh’s documentation uses the Google developer documentation style guide.
If your contribution includes substantial edits or additions, please
familiarize yourself with Google’s style guide. A simple way to get started
is using Google’s free technical writing courses.
You will find that many parts of Bokeh’s documentation do not yet follow
these style guidelines. We are currently working on implementing these
changes. However, we request that all documentation contributions follow
the standards described in this document.
Follow these basic guidelines in all your writing for Bokeh:
Be aware of sentence length. Try to avoid sentences that require more
than two commas. Consider breaking up longer sentences. You could also use
bulleted or numbered lists instead.
Avoid jargon or uncommon words and phrases. Keep in mind that many users of
Bokeh don’t use English as their primary language.
Use active voice instead of passive voice whenever possible.
Address the reader in the second person (‘you’). Avoid using the first
person (‘we’) or the third person (‘the user’).
Use American English spelling and grammar (refer to Merriam-Webster for
Use sentence case for headlines (capitalize words like in a regular
sentence, but do not use any punctuation at the end).
Use serial commas, also known as Oxford Commas.
Write in a way that is inclusive and accessible.
Activate the spell checker in your development environment.
Refer to the Google developer documentation style guide for more detailed
These are some commonly used terms and phrases and their spellings used
throughout the narrative documentation:
Always capitalize Bokeh and BokehJS
Capitalize both ‘J’ and ‘S’
Capitalize Jupyter, but not notebook
Don’t capitalize pandas
Always capitalize Python (the language)
For definitions and concepts used throughout Bokeh’s documentation, see the
Glossary in Defining Key Concepts.
In general, see the word list of the Google developer documentation style
guide for reference.
Bokeh uses Sphinx to generate the HTML files displayed at docs.bokeh.org. The
documentation is written in reStructuredText (ReST).
HTML is the only output format supported by Bokeh’s documentation. Many pages
To build the documentation, follow the instructions in Getting Set Up
and make sure you have activated the bkdev environment:
conda activate bkdev
Some of the examples in the documentation require additional sample
data. Use this command on a console to automatically download and install the
See Installing sample data for alternative instructions on how to
download the sample data.
In order to build the documentation, you must set the environment variable
GOOGLE_API_KEY. The documentation includes some plots with maps, and a valid
Google API key is required to build those plots correctly. You have two
Follow the instructions on the Google developers website to generate a new
Use a placeholder value like some_value instead of a valid API key. If
you use a placeholder, some map plots in Bokeh’s documentation might not be
rendered correctly, but the documentation should otherwise be built correctly.
This will only affect your local environment and should have no effect on any
changes you might commit to the Bokeh repository.
After activating your conda environment, use the following command to set the
conda env config vars set GOOGLE_API_KEY=some_value
Next, you have to reactivate your environment:
conda activate bkdev
Using conda env config vars set makes this environment variable part of your
bkdev environment. When you activate your bkdev environment, conda will from
now on set this environment variable for you.
conda env config vars set
You can find all source files for Bokeh’s documentation in the sphinx
directory of the Bokeh source tree.
Sphinx uses the standard Unix make command to control the build process. For
Windows users, the sphinx directory includes the file make.bat. Use this
Windows batch file instead of make, which is usually only available on
When building Bokeh’s documentation, the most common options for make are:
clean: remove all previously built documentation output. All output files
are generated from scratch on the next build.
html: build any HTML output that hasn’t been built yet or needs to be
rebuilt to include changes to the documentation source files.
serve: start a minimal web server and open a web browser to display the
docs. Starting a server is necessary because large portions of the
For example, to clean the docs build directory, run the following command:
You can combine multiple targets in one command (not supported by make.bat).
make clean html serve
Documents that you build yourself in your local environment load the most
recent version of BokehJS from Bokeh’s Content Delivery Network (CDN) by
default. If you would like to use your local version of BokehJS instead, set
the environment variable BOKEH_DOCS_CDN to local before calling make:
The documentation available at docs.bokeh.org mainly consists of those two
Docstrings and Model help text within the Python source code of Bokeh:
detailed explanations of all Bokeh modules and their properties. These texts
are available from the Python interpreter and within most Python development
environments. Sphinx also uses those texts to generate the API Reference
within Bokeh’s documentation.
Narrative documentation: tutorial-like descriptions and instructions for
Bokeh. This includes sections like the User guide, Developer guide or
All functions and methods in Bokeh use docstrings. In addition, Bokeh uses its
own system to provide detailed information on individual properties.
To automatically process all docstrings, Bokeh uses an extension for Sphinx
called Napoleon with Napoleon’s Google style. For Napoleon to work
correctly, all docstrings you write should follow the rules in the Google
Python Style Guide.
Docstrings for functions and methods generally include these three elements:
A short description of what the function or method does, starting with a
verb. For example: “Creates and returns a new Foo.”
Args: list all parameters, if any.
Returns: describe the return values of the function or method, even if the
function returns None.
def foo_function(name, level):
''' Creates and returns a new Foo.
name (str) :
A name for the Foo
level (int) :
A level for the Foo to be configured for
Bokeh’s model includes a system to provide documentation about individual
properties within the source code. You can add text to any property type by
passing a help argument.
Any string passed as a help argument can be formatted using
''' 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
renderers = List(Instance(Renderer), help="""
An explicit list of renderers to autorange against. If unset,
defaults to all renderers on a plot.
Bokeh’s narrative documentation consists of these for elements:
First steps: first steps guides and installation instructions
User guide: descriptions and instructions for using Bokeh
Gallery: interactive examples with source code
Developer guide: instructions for contributing to Bokeh
Sphinx generates each of those elements from reStructuredText (.rst) files. To
edit any of those elements, open the corresponding ReST source file in the
sphinx/source/docs folder of the Bokeh source tree.
For information on how to format text using reStructuredText, see the
reStructuredText primer on the Sphinx website or the official
For information on writing style, see Bokeh’s
documentation style guidelines
and the Google developer documentation style guide.
Release Notes are generally handled by the Bokeh core team as part of
Bokeh’s release management. 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.