Open bollwyvl opened 2 months ago
@meeseeksdev tag enhancement
Awww, sorry bollwyvl you do not seem to be allowed to do that, please ask a repository maintainer.
@blink1073 add the
enhancement
label 1 minute ago
I knew it! All the bots are just more Steves! :heart: :guitar:
Locally, it looks like the 1.4mb slug of JS doubles the size of the wheel:
383kb jupyter_server-2.14.0-py3-none-any.whl
792kb jupyter_server-2.15.0.dev0-py3-none-any.whl
That's... not actually as bad as I expected for a full, robust, and extremely useful app, but still pretty heavy.
It's possible that size could be further tightened up, but would likely require hundreds of megabytes of node_modules
to get a more purposeful build. I didn't even follow redocly
down this far, but imagine it's substantially larger on both fronts (and semi-shady).
I'll mark this ready for review, but am still not convinced it should be added to core, and will let others weigh in before going any further. For example:
page_config
or injected directlycurl
is magical and great, but i feel like having jupyter-adjacent code snippets (e.g. python
, browser
) would be more useful to usersBut really... extensions should be able to extend the spec via the existing conf.d
mechanism, and reference existing schema parts, and both extensions and core should be able to declaratively hide parts of the docs based on auth resources. And it should all be l10n-aware.
All of this points to complexity that would be better handled in an extension, and even if jupyter_server
:
jupyter_server[apidocs]
extra that depended on the new extensionDuring the jupyter servers and kernels call last week, @vidartf raised the question of exposing additional openapi specs. This points to another potential use case, where an extension (or otherwise wrapped service, e.g. via jupyter-server-proxy
) has an existing contract and would like it to be exposed via some mechanism, e.g. dropdown in the /apidocs
page:
:(). jupyter
[Jupyter Server v]
| Other Extension |
| Wrapped Appplication |
This could probably be deep linked via some GET param, e.g. /api/apidocs/?spec=/api/app1/swagger.yml
.
This doesn't handle the case where an extension overloads an existing route (perhaps by adding some new fields or metadata).
Another thought: currently docs/
is unclaimed. I've very much wanted to see a well-known location on disk (e.g. $PREFIX/share/jupyter/docs
which would allow other kinds of documentation to be hosted and, critically, made available via indexed search, and docs/api
might be a very nice place indeed to start that process. I'm currently unaware of a broadly-used way to describe "there's some interactive documentation at this relative URL," which seems like an important starting point to making this useful and discoverable.
references
1418
code changes
package.json
/api/apidocs
endpointalternatives
redoc
per https://github.com/jupyter-server/jupyter_server/issues/1418#issuecomment-2090954016node_modules
/api
(or evenapi/spec.yaml?docs
) would be strictly better, but these both seemed finicky to sniff based on headers, and sometimes be static file or JSON or whatever, and probably not worth the hasslespec.yaml
assessment
jupyter_server[apidocs]
would probably be pretty goodscreens
:bell: @Zsailer @tonyfast