[FEATURE] More documentation for (bundling) custom extensions

[tomascsantos]

Problem description

Hey Team,

I must begin with a thank you for the wonderful library you've created here. Now, the issue:

I've been all over the holoviz/panel and bokeh/bokeh repos and am struggling to figure out how to bundle a custom bokeh extension.

I've gotten to the point where my custom extension is working if I have node installed, however when I try to run in an environment without node I'm getting: node.js v14.0.0 or higher is needed to allow compilation of custom models. So began my deep dive...

I see that way back in 2018 there was something merged to allow for devs to override the cached behavior and provide their own compiled implementation:

#8336

This is implemented in panel here using some code like

    from bokeh.util.compiler import AttrDict, get_cache_hook, set_cache_hook
    old_hook = get_cache_hook()
    set_cache_hook(load_compiled_models)

Where load_compiled_models eventually depends on some private bokeh methods _get_custom_models and _compile_models.

Fast forward 500 PR's and @mattpap adds a new method to panel to using bokeh build to add panel's custom components: holoviz/panel#626

This PR is quite confusing to me:

1. all the __implementation__ lines are removed, so are they not needed? I notice that the bokeh extension docs still use this?
2. the functions load_compiled_models and build_custom_models have been removed. Presumably because now one can run bokeh build from the command line, but then how are the custom extensions registered with bokeh?

I would like to know how I may distribute my python package with my custom extension without requiring users to have node installed.

Finally, what kind of pitfalls exist with bokehjs / bokeh versions? If I use bokeh build while I have a particular bokeh version installed, how will this affect the versions of bokeh / bokehjs that my python package are compatible with?

Thank you for your consideration

Feature description

Would it be possible to connect the dots in the bokeh custom extensions documentation to explain how everything ties together and how one can compile and package custom extensions such that they can be shipped with a python package?

Potential alternatives

My alternatives have been scouring PR's and issues across panel and bokeh's repositories.

Additional information

No response

[matbryan52]

I'm faced with the same issue - a custom color Mapper which I'd like to bundle with a Python package - but it seems like the current doc is incomplete on how to actually distribute a pre-built extension.

[tomascsantos]

I see this issue is a duplicate from 2020: #9523, just linking for tidiness.

I'm excited by the "3.5" label @mattpap, If you have a draft of anything, I'm happy to review and test it out on my project so I can provide early feedback?