Sphinx bokeh_plot extension should work outside project docs

When using the sphinxext.bokeh_plot directive with the example from the docs, the sphinx build executes successfully (after following #5951). The js script is generated and copied into SPHINX_DOCS_ROOT_PATH/build/html/scripts/bokeh-plot-index-inline-5.js.

However when the file SPHINX_DOCS_ROOT_PATH/build/html/index.html is opened locally in chrome, the plot doesn’t render (although the code-block does), and the console gets the following error: Failed to load resource: net::ERR_FILE_NOT_FOUND with a link to file:///scripts/bokeh-plot-index-inline-5.js.

When I edited line 122 of PYTHON_LIB_PATH/bokeh/sphinxext/bokeh_plot.py from script_path = join("/scripts", js_name) to script_path = join("scripts", js_name), the plot appeared. I don’t know a lot about web development, so I don’t know if removing the / would break documentation hosted on a server.

Version Info:

Python version : 3.6.0 | packaged by conda-forge | (default, Jan 14 2017, 03:13:00) IPython version : 5.1.0 Bokeh version : 0.12.4 BokehJS static path : /Users/Atom/.anaconda/envs/py3/lib/python3.6/site-packages/bokeh/server/static node.js version : v6.3.1 npm version : 3.10.3 jupyter --version : 4.2.1 jupyter notebook --version : 4.3.1 os version : macOS 10.12.3 browser verision: Google Chrome Version 56.0.2924.87 (64-bit) sphinx version: 1.5.3

This is a really awesome sphinx extension!

[hallyourbase]

I have a a bit of a hacky solution to make it work for my specific use case. Unfortunately I don’t have a ton of time to find an elegant method worthy of a PR. What I ended up doing was:

• Place a known string ($REL_PATH$) at the front of the path when the script was parsed in _process_script
• finding the document depth in run by counting the ‘/’ chars in env.docname
• replace the tagged string with the appropriate number of ‘…/’ to find the script file relative to the current file containing the plot directive.

I am building my docs on Linux right now but it has been working with gh-pages with these changes. I can post more details on gist if it is any use to anyone.

[bryevdv]

@Benjamin-Lee Great, sure, most of the relevant code is in this file:

https://github.com/bokeh/bokeh/blob/master/bokeh/sphinxext/bokeh_plot.py

Things are a little complicated by the fact that there are three ways to include a plot:

• inline code in .rst file
• A py file in the docs source tree
• A py file outside the docs source tree

You can see these branches commented in the run method of the Directive. However, all of these paths use _process_script to generate the JS files, and to compute a path to the JS files for the script tag. Everything goes in env.bokeh_plot_files[js_name] = (script, js, js_path, source) And at the end everything uses build_finished to copy the JS files to the specified paths in the output.

So what is the task? Mostly bookkeeping. Those two function _process_script and build_finished currently make a location for the scripts a a fixed absolute path location in /scripts, and then copy them to the output in that location at the end. We want to make it more sophisticated, and instead generate locations that are right next to the source file that has the plot directive in it, and then copy the js scripts there, instead of the absolute path.

I think the first part of that is just calling autoload_static(d.roots[0], resources, js_name) instead of with script_path which is script_path = join("/scripts", js_name). That will generate a <script> tag with e.g. src="foo.js". And then for that to work, the builder_finished function at the end needs to be able to copy the js file into the proper location right next to the HTML output. I imagine, _process_script will need to compute the location, and then builder_fnished will look it up in env.bokeh_plot_files[js_name]