Update examples in documentation to work with version 3.0

I hope this is the right place to ask this, otherwise I can post somewhere else. I tried out the version 3 preview and noticed one important change in CDSView, it no longer accepts a source argument. I turns out that this argument was never really necessary from what I understand, but it was accepted. I only used that because I followed the pattern I saw in the documentation: First steps 8: Providing and filtering data — Bokeh 2.4.2 Documentation and Providing data — Bokeh 2.4.2 Documentation.

I have a double sided question and a regular question. If I submit a PR to branch-2.4, will the documentation be updated automatically, or would a release be needed? If a release were needed, would you consider doing that?

Are there any similar changes to look out for? I wasn’t able to find any 3.0 changelog. I wasn’t able to find any documentation for 3.0.0.dev2 even though it’s available on PyPI as a pre-release.

I think it would be very helpful as I was very confused as to why source stopped being necessary only to eventually discover it was never necessary yet is used in the examples.

Hi @OriolAbril we publish “dev” build primarily for the Bokeh dev team to use for testing, and for downstream projects (e.g. Dask, Panel, Holoviews, etc.) to test against. We do not really encourage regular users to use them, so we don’t publicize dev docs either. We do publish dev docs, but only for the latest dev release on each release branch, not for every dev release. You can find the 3.0 dev docs here:

Bokeh documentation — Bokeh 3.0.3rc1 Documentation

One we reason we do not encourage regular users to use “dev” builds is that we do not guarantee that CDN resources for dev builds will be permanently available. For this reason, you shold never, ever rely on a dev build “in production”.

If a release were needed, would you consider doing that?

Between minor releases, we can generally issue point releases easily any time. But things get a bit more difficult in front of a major release as the branches tend to diverge more. We are getting ready for a new major release that is still at least a months away. We would probably only bother with a 2.4.3 release for a very major bugfix at this point.

However, in this case, the change for source is only for 3.0+ so a fix for the docs should only go against branch-3.0 for the future 3.0 release, and not against branch-2.4. The current latest docs are correct for the current latest release (2.4.2).

Docs are generally updated as part of a feature PR, but it looks like this example was possibly missed, so a PR (against branch-3.0) would be appropriate and welcome. The change would show in the dev-3.0 docs whenever the next 3.0 dev build is released. (We don’t have any set schedule for those, they are made periodically as-needed.)

This is perfectly sensible, I wanted to make sure everything in ArviZ worked with the new release, wasn’t planning on using it yet for anything else.

Thank you so much for the link to the dev docs ! Is there a way to know the url “prefix” ? I did try dev but that points to 2.3.3rc1.

The doc source for branch-3.0 has already been updated, but I saw that later once I already had found the fix. In case it helps, my “journey” was:

1. find the error while testing arviz.plot_pair
2. Double check docs and see that docs (still) do exactly the same plot_pair does
3. search for 3.0 changelog but not be able to find it
4. check CDSView on github and find Remove `CDSView.source` and infer the source from `CDSView`'s parent by mattpap · Pull Request #11773 · bokeh/bokeh · GitHub
5. check docs source on branch-3.0

I wanted to ask because from the PR I got the impression that even if used in the docs, passing source wasn’t necessary and didn’t make much sense already in 2.x

For many years there was only the “dev” URL, because there was only one line of development. The dev-x.0 URLs are only recent, after we started keeping longer running branch-x.0 branches for parallel development. The URLs will always be dev-x.0 for corresponding branch-x.0, but probably only start with 2.4 IIRC.

search for 3.0 changelog but not be able to find it

Bad habits maybe, but we usually only make cursory changelog updates while development is in flight. There is always a dedicated PR right before a release to clean up or flesh out the release guide guide. There’s been some discussion about being more proactive and also including an Unreleased release notes section, but it’s not work anyone has decided to dedicate their time to as of yet.

@OriolAbril BTW We do run a collection of downstream tests on CI:

bokeh/run_downstream_tests.sh at branch-3.0 · bokeh/bokeh · GitHub

These tests are purely informative (i.e. they will never fail the build) but do provide some potential indication of unexpected incompatibilities or issues that the main tests don’t catch.

If Arviz has a subset of Bokeh-related tests that would make sense to include there, we’d be happy to have them added.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.