Documentation and API of BokehJS in the future

I’m happily using BokehJS in some front-end work that I’m doing. It’s a great deal more powerful than the alternatives like chartist and google charts, but the documentation is comparatively quite poor.
I’m on the fence in the future about switching to plot.ly, but the open source aspect of BokehJS is keeping me pinned for now, even though plot.ly looks better by default, is simpler to use, and has more documentation.

I was wondering what the future of the documentation of BokehJS and the API of BokehJS is? I haven’t been able to find a roadmap or a plan.

Best,

Alex

Hi Alex,

You are correct about the currnt state of the JS docs and interface at the moment. There was initially a very simplistic "higher level" interface for BokehJS that was never intended to be permanent, and in fact it was broken and removed with 0.7. However, we are committed to creating a stable and documented interface (both high level and "object" level) for the client library. In particular there is an issue for creating a new higher level BokehJS interface here:

  https://github.com/bokeh/bokeh/issues/1515

This is targeted for Bokeh 0.8 which is expected in mid February. This higher level interface will have API docs (something the old prototype did not have) and once it is in place we will update all the Bokeh examples on JSFiddle, and hopefully add several new ones.

Along with this, there is also this issue regarding adding auto-generated reference docs for all JSON objects in the BokehJS protocol:

  Auto document JSON for bokeh.models · Issue #1579 · bokeh/bokeh · GitHub

This is primarily intended to be helpful to anyone generating language bindings around BokehJS, but of course should be very useful to anyone using BokehJS directly as well. It's possible this will be available for our 0.7.1 release next week, but even if it is not in the release, it will be available on our "dev docs" site sometime in the next two weeks (I am out teaching next week so it may take until the following week)

A little further down the line, prior to a 1.0 release we intend to have the protocol versioned and provide validators.

So the short answer is yes, the JS interface is an important priority for us, and furthermore we are finally at a place of enough stability that we can actually put effort into it without having to worry that it will be thrown away in 6 months. That said, as with all OSS projects, we could use help. :slight_smile: I definitely encourage you to chime in on the issues above, or any others that are relevant. Suggestions for JS docs tools or formats, API design, etc. would all be very welcome, as would any code contributions, naturally!

Thanks,

Bryan

···

On Jan 7, 2015, at 3:10 PM, Alex W <[email protected]> wrote:

I'm happily using BokehJS in some front-end work that I'm doing. It's a great deal more powerful than the alternatives like chartist and google charts, but the documentation is comparatively quite poor.
I'm on the fence in the future about switching to plot.ly, but the open source aspect of BokehJS is keeping me pinned for now, even though plot.ly looks better by default, is simpler to use, and has more documentation.

I was wondering what the future of the documentation of BokehJS and the API of BokehJS is? I haven't been able to find a roadmap or a plan.

Best,
Alex

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/5a5e8b77-47f8-45c0-8d0e-b0cae6d56a1d%40continuum.io\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

Is there a style guide or any onboarding docs for contributing to BokehJS?

···

On Wed, Jan 7, 2015 at 4:28 PM, Bryan Van de Ven [email protected] wrote:

Hi Alex,

You are correct about the currnt state of the JS docs and interface at the moment. There was initially a very simplistic “higher level” interface for BokehJS that was never intended to be permanent, and in fact it was broken and removed with 0.7. However, we are committed to creating a stable and documented interface (both high level and “object” level) for the client library. In particular there is an issue for creating a new higher level BokehJS interface here:

    [https://github.com/bokeh/bokeh/issues/1515](https://github.com/bokeh/bokeh/issues/1515)

This is targeted for Bokeh 0.8 which is expected in mid February. This higher level interface will have API docs (something the old prototype did not have) and once it is in place we will update all the Bokeh examples on JSFiddle, and hopefully add several new ones.

Along with this, there is also this issue regarding adding auto-generated reference docs for all JSON objects in the BokehJS protocol:

    [https://github.com/bokeh/bokeh/issues/1579](https://github.com/bokeh/bokeh/issues/1579)

This is primarily intended to be helpful to anyone generating language bindings around BokehJS, but of course should be very useful to anyone using BokehJS directly as well. It’s possible this will be available for our 0.7.1 release next week, but even if it is not in the release, it will be available on our “dev docs” site sometime in the next two weeks (I am out teaching next week so it may take until the following week)

A little further down the line, prior to a 1.0 release we intend to have the protocol versioned and provide validators.

So the short answer is yes, the JS interface is an important priority for us, and furthermore we are finally at a place of enough stability that we can actually put effort into it without having to worry that it will be thrown away in 6 months. That said, as with all OSS projects, we could use help. :slight_smile: I definitely encourage you to chime in on the issues above, or any others that are relevant. Suggestions for JS docs tools or formats, API design, etc. would all be very welcome, as would any code contributions, naturally!

Thanks,

Bryan

On Jan 7, 2015, at 3:10 PM, Alex W [email protected] wrote:

I’m happily using BokehJS in some front-end work that I’m doing. It’s a great deal more powerful than the alternatives like chartist and google charts, but the documentation is comparatively quite poor.

I’m on the fence in the future about switching to plot.ly, but the open source aspect of BokehJS is keeping me pinned for now, even though plot.ly looks better by default, is simpler to use, and has more documentation.

I was wondering what the future of the documentation of BokehJS and the API of BokehJS is? I haven’t been able to find a roadmap or a plan.

Best,

Alex

You received this message because you are subscribed to the Google Groups “Bokeh Discussion - Public” group.

To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].

To post to this group, send email to [email protected].

To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/5a5e8b77-47f8-45c0-8d0e-b0cae6d56a1d%40continuum.io.

For more options, visit https://groups.google.com/a/continuum.io/d/optout.

You received this message because you are subscribed to a topic in the Google Groups “Bokeh Discussion - Public” group.

To unsubscribe from this topic, visit https://groups.google.com/a/continuum.io/d/topic/bokeh/NyZpHvd9LIU/unsubscribe.

To unsubscribe from this group and all its topics, send an email to [email protected].

To post to this group, send email to [email protected].

To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/5CF5C4B0-8ABE-4CB0-975A-0FEF4B542512%40continuum.io.

For more options, visit https://groups.google.com/a/continuum.io/d/optout.

Alex,

There is not a strict coding style guide, per se. For python it's roughly PEP8. For the coffeescript side, there is this minimal document:

  https://github.com/bokeh/bokeh/blob/master/bokehjs/docs/html/docs/style_guide.html

Our development process is thoroughly outlined in the BEP documents on the GH Wiki:

  Home · bokeh/bokeh Wiki · GitHub

Especially BEP 1 describes our team process for PRs and and issues. I would say most outside PRs do not conform to this, but we are not in a position to reject outside contributions out of hand for that. :slight_smile: But anyone interested in contributing (especially on any larger piece of work) is encouraged to adopt that workflow.

There is also the main docs developer guide:

  Contribute — Bokeh 3.3.2 Documentation

Most of this information is geared towards the python side but there is also a fair chunk of info about BokehJS dev there as well.

Thanks,

Bryan

···

On Jan 7, 2015, at 3:34 PM, Alex Wiltschko <[email protected]> wrote:

Is there a style guide or any onboarding docs for contributing to BokehJS?

On Wed, Jan 7, 2015 at 4:28 PM, Bryan Van de Ven <[email protected]> wrote:
Hi Alex,

You are correct about the currnt state of the JS docs and interface at the moment. There was initially a very simplistic "higher level" interface for BokehJS that was never intended to be permanent, and in fact it was broken and removed with 0.7. However, we are committed to creating a stable and documented interface (both high level and "object" level) for the client library. In particular there is an issue for creating a new higher level BokehJS interface here:

        https://github.com/bokeh/bokeh/issues/1515

This is targeted for Bokeh 0.8 which is expected in mid February. This higher level interface will have API docs (something the old prototype did not have) and once it is in place we will update all the Bokeh examples on JSFiddle, and hopefully add several new ones.

Along with this, there is also this issue regarding adding auto-generated reference docs for all JSON objects in the BokehJS protocol:

        Auto document JSON for bokeh.models · Issue #1579 · bokeh/bokeh · GitHub

This is primarily intended to be helpful to anyone generating language bindings around BokehJS, but of course should be very useful to anyone using BokehJS directly as well. It's possible this will be available for our 0.7.1 release next week, but even if it is not in the release, it will be available on our "dev docs" site sometime in the next two weeks (I am out teaching next week so it may take until the following week)

A little further down the line, prior to a 1.0 release we intend to have the protocol versioned and provide validators.

So the short answer is yes, the JS interface is an important priority for us, and furthermore we are finally at a place of enough stability that we can actually put effort into it without having to worry that it will be thrown away in 6 months. That said, as with all OSS projects, we could use help. :slight_smile: I definitely encourage you to chime in on the issues above, or any others that are relevant. Suggestions for JS docs tools or formats, API design, etc. would all be very welcome, as would any code contributions, naturally!

Thanks,

Bryan

> On Jan 7, 2015, at 3:10 PM, Alex W <[email protected]> wrote:
>
> I'm happily using BokehJS in some front-end work that I'm doing. It's a great deal more powerful than the alternatives like chartist and google charts, but the documentation is comparatively quite poor.
> I'm on the fence in the future about switching to plot.ly, but the open source aspect of BokehJS is keeping me pinned for now, even though plot.ly looks better by default, is simpler to use, and has more documentation.
>
> I was wondering what the future of the documentation of BokehJS and the API of BokehJS is? I haven't been able to find a roadmap or a plan.
>
> Best,
> Alex
>
> --
> You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
> To post to this group, send email to [email protected].
> To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/5a5e8b77-47f8-45c0-8d0e-b0cae6d56a1d%40continuum.io\.
> For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

--
You received this message because you are subscribed to a topic in the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this topic, visit https://groups.google.com/a/continuum.io/d/topic/bokeh/NyZpHvd9LIU/unsubscribe\.
To unsubscribe from this group and all its topics, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/5CF5C4B0-8ABE-4CB0-975A-0FEF4B542512%40continuum.io\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/CAGcyYLS8hrXvjA2%3D9XTfNu9sK-%3D1h2n3z689i5sfpSbAatHyMA%40mail.gmail.com\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.