Issues building Sphinx documentation

Hi all,

I’m trying to build Sphinx Bokeh documentation locally. I was able to build bokeh from source code as explained in the docs.
Then, I tried to build the sphinx documentation executing make clean html serve from sphinx directory. But it failed with the following stacktrace message

copying bokeh-plot files... [100%] bokeh-plot-ff6c70ba491245fb8b627143af821b5d-external-docs-reference-models-glyphs-image_url.js

Exception occurred:
  File "/Users/teresa/Documents/gsod/bokeh/bokeh/sphinxext/bokeh_plot.py", line 159, in run
    raise RuntimeError("Sphinx bokeh-plot exception: \n\n%s\n\n Failed on:\n\n %s" % (e,source))
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)

 Failed on:

 from bokeh.io import output_file, show
from bokeh.models import ColumnDataSource, GMapOptions
from bokeh.plotting import gmap

output_file("gmap.html")

map_options = GMapOptions(lat=30.2861, lng=-97.7394, map_type="roadmap", zoom=11)

# For GMaps to function, Google requires you obtain and enable an API key:
#
#     https://developers.google.com/maps/documentation/javascript/get-api-key
#
# Replace the value below with your personal API key:
p = gmap("GOOGLE_API_KEY", map_options, title="Austin")

source = ColumnDataSource(
    data=dict(lat=[ 30.29,  30.20,  30.29],
              lon=[-97.70, -97.74, -97.78])
)

p.circle(x="lon", y="lat", size=15, fill_color="blue", fill_alpha=0.8, source=source)

show(p)
The full traceback has been saved in /var/folders/jh/00zjdgcs6313msk2myxz1yd40000gn/T/sphinx-err-y7w71eu7.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

Related to this error message, I found out the following bug which was already solved.
I am using OSX system and here it is the Bokeh installed information

(bokeh-dev) Teresas-MBP:bokeh teresa$ python -m bokeh info
Python version      :  3.7.7 (default, May  6 2020, 04:59:01)
IPython version     :  7.13.0
Tornado version     :  6.0.4
Bokeh version       :  2.0.2-36-g949661944-dirty
BokehJS static path :  /Users/teresa/Documents/gsod/bokeh/bokeh/server/static
node.js version     :  v10.13.0
npm version         :  6.14.5
(bokeh-dev) Teresas-MBP:bokeh teresa$ BOKEH_RESO

I wanted to know how can I solve this issue or if you can give me guidance or suggestions about it.

Thanks!

Hi @tfodesant Use of Google Maps APIs requires using an API key from Google. We have our docs build settings set strictly to fail if GOOGLE_API_KEY is not defined. The reason for that is as a precaution against accidentally publishing docs with broken gmap examples! You could get an API key from Google and use that, however, if you don’t care if gmap examples work or not, you can also just set to any junk value, e.g.

GOOGLE_API_KEY="junk" make clean html serve

This should probably be added to the Deb Guide.

Hi @Bryan
Thanks for your explanation! You’re right about to prevent publishing docs with broken gmap examples.
Also, I have another question: in order to contribute, Must we register the issue on Github first? Or can we propose the PR without a Github issue linked?
Thanks!

We generally prefer and issue to link to first, but if it is a very small single-file change then it’s OK to just submit a PR by itself!