Hey, help me please to find an offline documentation version.
Better if it is the html format.
The docs hosted https://docs.bokeh.org are all that we publish. Bokeh Is a library whose express purpose is generating JavaScript content for browsers. All total, the docs contain hundreds of individual JavaScript scripts. Due to the way browsers handle security, these have to be loaded from a real web server (i.e. not local files) in order to function properly, so there is no value/incentive to providing anything else.
Correct me if i’m wrong, it looks like Bokeh documentation is built by Sphinx. In such the case, i think there is a capability to generate it as other PyData organization OSS libraries as pandas or networkx.
Though, i understand difficulties in generating a static documentation with a lot of JS files due to having my own experience in generating Sphinx docs.
The documentation is built with Sphinx, with lots of custom extensions. The built docs load BokehJS from the public CDN at cdn.bokeh.org. Even if we published a HTML tarball or something, it would not really be usable “offline” since none of the hundreds of plots in the docs would render at all without a network connection to reach the CDN. That does not seem very useful to me. I am not really sure what exactly you are asking for, though.
Well, i’m not asking really, but trying to get some more details on why js files couldn’t be included into an html tarball to run it locally. Downloading them from the CDN makes it impossible to read offline of course. May be you give a couple of words about “browsers handle security” just to know it?
Bokeh can generate output with inline JS data and resources, and in fact many people use this to create documents that work on airgapped or otherwise isolated networks. But the docs are not configured that way, because there are a number of downsides:
- the docs pages are already fairly heavy, doing this will balloon many page sizes
- worse, browser JS caching is rendered completely ineffective so repeated views won’t improve
But that’s just the UX side, there’s problems from the maintainers POV as well:
- Anything that adds complexity to the build/release automation is a giant risk, and being based in CI, is enormously time-consuming to debug and test
- The docs take ~20 minutes to build in CI, adding this would double that. Our full release job already gets close 75% of GH action max time. We might need to split the release build into multiple jobs, which is frankly a nightmare to consider.
- Edit: there is sphinx extension implementation work that is needed to even make it possible to begin with.
I am not trying to be overly negative here, but like almost all OSS maintainers, Bokeh’s core team is continuously oversubscribed. [1] You are the only person I can recall asking for this in ~11 years, and making it happen would be a lot of work. I hope you can recognize why it’s not likely to rise to the top of any priority lists any time soon.
TBH I think your best bet is to try to build the docs yourself with inline resources, I am happy to answer any questions or offer guidance that I can.
Edit: actually nevermind that last bit, the docs cannot currently be built with inline resources, since the sphinx extensions currently always uses either CDN, or local http server:
I’m sorry but I don’t have any good suggestions to offer you are this time. It might be simply work to add a mode="inline" codepath to the function above, but maybe its more complicated. Someone would just have to try and see.
If you want a “tarball” of the currently deployed docs, I can happily get it to you as a one-off, but plots will not work unless the CDN is network accessible, as stated above.
-
e.g. I have personally just spent 20-30 hours a week on top of my day job for the last ~6 weeks executing a major restructuring and improvement to the user guide, gallery, and examples repo leading up to the 3.0 release. ↩︎
1 Like
You are the only person I can recall asking for this in ~11 years
Yeah, i realize it 
It might be simple to add an “inline” option to the code above, but it might not be
Sure, i don’t put any expectation on it.
I can happily get it to you as a one-off
Let me have and test it out. I hope my need is partly satisfied. Could you attach it to this thread?
And thank you for comprehensive explanation. I understand how intensive maintaining OSS project is along with a full-time job.
@kvdm.dev For simplicity, I have temporarily placed a copy here: https://static.bokeh.org/docs-3.0.0.tgz Please let me know when you have grabbed it so that I can remove it.
I would add that if this already-existing tarball is useful for people, it would not be too much effort to start making it publicly available somewhere. (e.g. a dedicated folder under docs.bokeh.org would probably be the simplest, since we are already uploading things there during a release)
1 Like
Please let me know
Done.
I’m clicking the doc around and it still useful even without the plots(turned off network for a short while to test) as i can quckly copy code, paste and run it locally to see a result. At least i can read First steps, User Guide, References which is what i basically need. Gallery is obviously empty.
I would add that if this already-existing tarball is useful for people
If there is a trivial, small effort way to replace charts with according pictures, exported png for example, it would be quite useful in my opinion. If not, it doesn’t worth to publish…
1 Like
I think we can accommodate uploading the tarball fairly easily. Please make a GitHub Issue about it!
For what it’s worth, I’d also be interested in an off-line readable version of the Bokeh docs. I use Bokeh on an isolated network where access to online documentation is not convenient. I don’t need the latest/greatest version of the docs, just something reasonably current would be appreciated.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.