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)
- Can't build extensions on Windows
- [BUG] <b> and <strong> ignored in tooltips on Firefox HOT 3
- Move sampledata files to pip/conda installable package HOT 6
- [BUG] TableColumn visible property is not working if a column is added after the DataTable is created
- [BUG] autosize_mode prevents DataTable values to be updated
- [FEATURE] Support directory upload and clearing inputs from Python for `FileInput` widget
- [BUG] BokehJS standalone initialization fails HOT 8
- [BUG] Custom CSS broken HOT 3
- Docs sidebars take up way to much space HOT 4
- BokehJS docs page has issues HOT 2
- [BUG] figure.circle produces empty plot when used datetime axis HOT 5
- Bokeh.Plotting.figure.circle in bokehjs can't find `x` and `y` in a ColumnDataSource HOT 1
- CI jobs should fail immediately (or retry) if package install fails
- Remove typing_extenions at minpy 3.11
- [BUG] Tooltips not shown when plot is in fullscreen HOT 1
- [BUG] NPM package has types (*.d.ts) in incorrect location
- [FEATURE] Custom sorting of columns in a table HOT 1
- `Tooltip` is initially attached to the DOM when it shouldn't be
- Inner canvas layers need `overflow: hidden` after PR #13863
- [BUG] Typing of layouts.gridplot expects wrong type if ncols given
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.