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 contributor.
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 development environment.
Where to get started¶
An easy way to start contributing to Bokeh’s docs 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 documentation issues on GitHub. This list contains several projects as a starting point.
Documentation style guidelines¶
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.
Principles of good style¶
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 consistent spelling).
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.
Use a spell checker in your development environment.
Refer to the Google developer documentation style guide for more detailed information.
Commonly used terms¶
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)
In general, see the word list of the Google developer documentation style guide for reference.
Setting up and building Bokeh’s documentation¶
1. Prepare your environment¶
To build the documentation, follow the instructions in Setting up a development environment
and make sure you have activated the
bkdev environment in your console:
conda activate bkdev
Unless you have just installed or updated your conda environment, you should
make sure that all the packages are up to date. Run this command from the
root level of your source checkout directory to update
conda env update --file environment.yml --prune
Some of the examples in the documentation require additional sample data. Use this command to automatically download and install the necessary data:
See Installing sample data for alternative instructions on how to download the sample data.
2. Set environment variable¶
In order to build the documentation, you must set the
documentation includes some plots with maps, and a valid Google API key is
required to build those plots correctly. You have two options:
Follow the instructions on the Google developers website to generate a new API key.
Use a placeholder value like
some_valueinstead 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 environment variable:
conda env config vars set GOOGLE_API_KEY=some_value
Next, you have to reactivate your environment:
conda deactivate conda activate bkdev
conda env config vars set makes this environment variable part of your
bkdev environment. Whenever you activate your
bkdev environment, conda
will now set this environment variable for you.
3. Build Bokeh’s documentation¶
You can find all source files for Bokeh’s documentation in the
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
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.
To build the docs, run the following command:
After building the docs, run the following command to start a server and display the docs in a web browser:
Linux/macOS only: You can combine multiple targets in one command (not
make.bat). For example:
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
local before calling
BOKEH_DOCS_CDN=local make clean html serve
$Env:BOKEH_DOCS_CDN = "local" ./make.bat html ./make.bat serve
set BOKEH_DOCS_CDN=local make.bat html make.bat serve
To speed up the build of your local documentation, you have the option to use
an experimental Sphinx feature that distributes the build process over
several CPUs and cores. This only works on Linux and macOS (not on Windows). On
macOS, this feature only works on Python 3.7. To use this experimental feature,
add the option
SPHINXOPTS="-j auto" to your build command:
make clean html serve SPHINXOPTS="-j auto"
To learn more about options for the Sphinx build process, see sphinx-build in the Sphinx documentation.
Writing Bokeh’s documentation¶
The documentation available at docs.bokeh.org mainly consists of those two elements:
- Narrative documentation
- Docstrings and Model help text within the Python source code of Bokeh
This part of the documentation consists of 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 reference guide section of Bokeh’s documentation.
In the file sphinx/source/rst_epilog.txt, you can find many common
substitutions used across the narrative documentation as well as docstrings and
model help texts. This file is loaded as the
epilog.rst environment variable for Bokeh’s
Writing for Bokeh’s narrative documentation¶
Bokeh’s narrative documentation consists of these four elements:
First steps: first steps guides and installation instructions
User guide: descriptions and instructions for using Bokeh
Gallery: interactive examples with source code
Contributor 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.
Contributing to Bokeh’s source code documentation¶
To automatically process Python docstrings, Bokeh uses an extension for Sphinx called Napoleon with Napoleon’s Google style. For Napoleon to work correctly, all docstrings you write need to follow the rules in the Google Python Style Guide.
Docstrings generally include these three elements:
A short description of what the function does, starting with a verb. For example: “Create and return a new Foo.”
Args: list all parameters, if any.
Returns: describe the return values of the function, even if the function returns
def foo_function(name, level): ''' Creates and returns a new Foo. Args: name (str) : A name for the Foo level (int) : A level for the Foo to be configured for Returns: Foo '''
Writing models and properties help¶
Bokeh’s models use a custom system to provide documentation about individual
properties directly in the source code. You can add this kind of text to any
property type by including a
Any string passed as a
help argument can be formatted using
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. """)
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 build will automatically add this content to the list of all releases.