Quickstart and Getting Started example is not obvious

There is nothing on the Quickstart page that explains how to execute a bokeh script at the command line.

bokeh serve --show works well and the Jupyter notebooks seem quite popular but I don’t use them.

I’ve tried every option for bokeh command line and gotten errors on each of them except for json, svg, and png. I don’t know what to do with the json file and don’t need to make an svg or png.

How is bokeh supposed to be run from the command line on Ubuntu?

The Getting Started example doesn’t seem to work with:
bokeh html basic_plot.py

It gives this error:
ERROR: OutputDocumentFor expects a sequence of Models

Shouldn’t this work at the command line?

@comparem With the exception of bokeh serve many of the command line commands e.g. bokeh html were an idea/experiment of a former contributor several years ago, Do they work well? I don’t know, all I know is that the tests pass I’ve never used them, we’ve never heavily promoted them, as far as I can recall you are the first person to ask about them. They are not on the Quickstart because they are not a common way to use Bokeh, nor do we intend or imagine them to be the standard way to use Bokeh. At this point, it’s possible they should just be removed, if there is not someone who wants to take care of them.

It would probably help to know more about what you actually want to accomplish, so we can guide you to more typical and established usage. There are APIs for generating HTML, PNG, etc outputs.

Hello Bryan,

This is enlightening to learn the command line options aren’t supported, or perhaps aren’t the intended workflow. That would explain their lack of prominence in the Quickstart guide.

I’ve gotten bokeh serve to work and like it a lot, but I still have no idea how to run Bokeh with the intended workflow with output_file().

Jupyter Notebooks seems to be important but it uses output_notebook() rather than output_file().

I’d like to run the simple Bokeh script right from the Quickstart page but there is no explanation how to do this. It says:

“When you execute this script, you will see that a new output file "lines.html" is created, and that a browser automatically opens a new tab to display it.”

That sounds great. How does this happen?

What is the normal, expected workflow to execute a Bokeh script?

Marc

Ok, this seems obvious in hindsight, but the bokeh executable (in /usr/local/bin for my system) is only relevant for the bokeh serve command which fires up Tornado web server and continues interactively.

But to simply execute a bokeh script, I chmod +x basic_plot.py to make this file executable on Ubuntu linux and add #!/usr/bin/env python3 as the first line.

This tells bash to execute basic_plot.py as a python3 script and seems to work well.

The /usr/local/bin/bokeh executable is not called directly when using the output_file() function.

That was my mistake. I was trying to execute an output_file() script with the bokeh executable.

This may be obvious, but it took me a bit to stop trying to use the bokeh command.

Is this the expected workflow? What is the intended, common, normal usage?

This is enlightening to learn the command line options aren’t supported

I would say this is too strong a statement. Not every part of a library is equally important, and these parts are definitely on the low end of the spectrumm—as evidenced by the fact that AFAIK they probably still work as designed (tests still pass) but I have no experience to offer.

The most common way to save HTML output from Bokeh is to call output_file(filename) in a regular Python script, and then (usually at the end) a call to show(plot) or save(plot). You can see this pattern in every example under examples/plotting/file.

That sounds great. How does this happen?

Taking specifically the iris.py example from the directory above:

python iris.py

will save an iris.html file (and open it in a new browser tab). You could also add a “shebang” and chmod +x a Python script to be able to “run it directly” but, at least personally, I never do that. I think most people just use the python executable, as above.

Bryan,
Thanks - this is pretty obvious in hindsight. I went down the path of bokeh serve to run scripts and had to backtrack to executing a normal python script.

Simple as it is, this still is not mentioned in the Quickstart guide.

And actually, after checking, I think those commands might be broken after all. I’ve opened a GitHub issue to propose removing them entirely for upcoming 2.0 release.

Simple as it is, this still is not mentioned in the Quickstart guide.

There is always room for refinement. If you would like to make any edits to the Quickstart a PR would certainly be appreciated. The relevant file is here:

https://github.com/bokeh/bokeh/blob/master/sphinx/source/docs/user_guide/quickstart.rst