to “Troubleshooting” as the section title. We can list out some common errors users may encounter when building docs locally and suggestions to fix them. Commons errors meaning the user has all the requirements needed to build the docs but there’s something wrong with the syntax they’re using when updating the docs, Sphinx configurations are incorrect, etc.
As a first time contributor, I’ve listed some of the issues I encountered down below and how they would look in a “Troubleshooting” section. I could go through the Discourse forum and try to aggregate any other issues that may fall under common errors.
1.RuntimeError: Sphinx bokeh-plot exception:
The GOOGLE_API_KEY environment variable is not set. Set GOOGLE_API_KEY to a valid API key, or set bokeh_missing_google_api_key_ok=True in conf.py to build anyway (with broken GMaps)
Run GOOGLE_API_KEY=foo make clean html serve when building docs or set bokeh_missing_google_api_key_ok=True in conf.py.
2.docstring of bokeh.models.annotations.Whisker:3:undefined label: _userguide_plotting_whiskers (if the link has no caption the label must precede a section header)
When including Sphinx labels inside docstrings, remove the leading prefix found in the reStructuredText doc.
.. _userguide_plotting_whiskers:
Whiskers
--------
A |Whisker| will ...
class Whisker(Annotation):
''' Render a whisker along a dimension.
See :ref:`userguide_plotting_whiskers` for information on plotting whiskers.
'''
Final thoughts:
I noticed for suggestion #1 there was a pull request merged to hopefully avoid this but I think it’d be useful to call out this error and mention the second option of setting bokeh_missing_google_api_key_ok=True in conf.py
Maybe suggestion #2 should go under Source Code Documentation instead of under “Troubleshooting”. Either way, I think calling this out in our own docs is helpful since it’s mentioned in the Sphinx docs and first time contributors may not be familiar with the syntax:
Reference labels must start with an underscore. When referencing a label, the underscore must be omitted (see examples above).
Source: reStructuredText Primer — Sphinx documentation
