Comments (9)
I am very much in favour of this.
There might be some overlap with BokehJS if we manage to elevate that to a standalone NPM package as we'd need API docs for that, and ideally both sets of API docs would be organised along similar lines for ease of mentally switching between the two. The BokehJS model classes are already split into sensible groups so it would be good to do similar on the Python side.
from bokeh.
@ianthomas23 can you elaborate? The structure on Bokeh sides should still be identical AFAIK. The only difference is that on the Python side model definitions are small so a module like models/ranges.py
defines several models in one file. But implementations on the JS side are typically much larger, so are split out one more level, with a models/ranges
directory, that contains individual files for each model implementation.
I'm not sure how that pertains here, though. These things are all distinct:
- API presented to users
- file/module layout on disk
- organization of the docs
So just being clear, this issues is not about expecting users do from bokeh.models.ranges import Range1d
instead of from bokeh.models import Range1d
. IMO that is Bokeh 4.0 territory. It's also not about splitting up ranges.py
to a ranges
directory to match BokehJS (that seems excessively fine-grained on the Python side) This issue is just about the docs presentation and can be summed up "stop generating enormous pages".
from bokeh.
Just noting that I can get a basic configuration with autoapi
building (with some new warnings) but for the results are still mixes, e.g. the help strings for properties are not currently being rendered, so some continued investigation is needed.
from bokeh.
@bryevdv I assumed that
There are some questions that probably intersect with this, such as the idea to split up the monolithic bokeh.models namespace itself at the user-facing API level (cc @mattpap I thought there was an issue/discussion about this but I can't find it)
meant splitting up the Python directory/class structure to be more fine-grained, but you have said this isn't so. My mistake.
from bokeh.
meant splitting up the Python directory/class structure to be more fine-grained, but you have said this isn't so. My mistake.
@ianthomas23 no mistake I just hadn't imagined that was something people wanted, since it seems like it will result in hundreds of very small files. I'd like to understand what benefits you identify in splitting things up more are? Entirely possible I just don't see them, but I can learn :)
from bokeh.
I think the docs over at @snehilvj/dash-mantine-components have a great way of displaying each widget with examples and full docs, as shown here, with one page per widget.
from bokeh.
I don't think autoapi
is going to be an option, AFAICT it is just completely independent of autodoc
directives meaning all our custom extensions for models, properties, enums, etc. will not function. I will look at sphinx-apidoc
and/or sphinx.ext.autosummary
next, which should explicitly work together with autodoc
.
from bokeh.
@ianthomas23 I am actually starting to come to the conclusion that "one page per model" may in fact not be possible unless we adopt the fine-grained split you suggested... (or else write yet another custom extension or literally hand-author hundreds of ReST files, but I am loathe to consider either of those options)
from bokeh.
unfortunately autosummary
is also currently a non-starter due to a Sphinx limitation sphinx-doc/sphinx#12021
Bokeh has unusual requirements, and I am not sure there is any immediate path forward without more custom tooling. I'm not sure when/if I would have bandwidth to look at that.
from bokeh.
Related Issues (20)
- [BUG] sizing mode issue with layout and nested rows, columns HOT 1
- [BUG] Compilation of Bokeh extension fails in the presence of a package.json file with type: module HOT 1
- [BUG] DataTable inside Dialog HOT 1
- [BUG] JS errors on Bokeh docs page HOT 7
- [FEATURE] Codes for categorical data
- [DOC] Boxplot example: some whiskers and vbar are rendered slightly asymmetrically and boldly HOT 3
- [FEATURE] Allow bokeh server embed script to forward credentials HOT 6
- Example code block for CustomJSFilter is missing
- create CompositeFormatter to enable HTMLTemplateFormatter with other formatters such as NumberFormatter HOT 2
- Refdocs anchors do not work HOT 2
- [BUG] 3.4.0: Selection glyph no longer employs selection_glyph properties HOT 2
- `InputWidget.title` doesn't update anymore HOT 1
- [BUG] Switching order of children in layout has no effect
- [BUG] SaveTool generates smaller image than plot (especially in gridplot) in BokehJs
- [BUG] Bokeh doesn't support IPv6 websocket origins HOT 4
- [BUG] Can't set reuse_port in bokeh.server.util bind_sockets HOT 2
- [BUG] Cannot `micropip.install("bokeh>=3.4.0")` HOT 8
- activate pydata-sphinx-theme version banner
- Build job failing due to version mismatch HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from bokeh.