Declarative Tours?

[bollwyvl]

This is a very useful feature! I miss having something like this from classic, when bootstrap-tour was always right there.

I'd love to see the DX of building a tour extended into a more declarative format. While joyride has a lot of features that only make sense with the full JS API, there's a lot of stuff one could build declaratively without having to learn any React/JSX... or, more importantly, recompile Lab to see a small change. Draft 7 JSON Schema seems like a good choice, as ajv is already hanging around.

I guess the simplest form of this would be a lumino command, e.g. jupyterlab-tour:start-tour with an args of {steps: [{target: '#main', content: 'hello world!'}]}. This would allow an extension to not even have to know about the ITourManager.

Document: Putting a conforming schema instance into a file e.g. my-feature.tour.json would also make it possible to have a default "Start Tour" from the file browser. This would play very nicely with existing features like the router commands, e.g. lab/tree/my-feature.tour.json, and would feel great with nbgitpuller, etc. It could be JSON5, again, because it's already lying around and slightly improve the end user experience, but JSON is probably a more portable solution, while YAML/TOML would be more humane.

Editing: An Open With... ▶︎ Tour Editor with something like react-jsonschema-form could then do round-trip editing of a tour, with a one-click "preview". I've wrapped rjsf up in lumino/lab stuff, with a few goodies like a codemirror widget, in jupyterlab-rjsf so it could be relatively straightforward to drop into a MainAreaWidget without a lot of effort.

Cosmetics: A few key props, llke step.content and .title, which are expecting a react component, could also be markdown, perhaps with a flag or alternate prop, e.g. markdownContent. Or, an even more jupyter-like way to do it would be a mimembundle... i don't know why you'd want to have a CSV, but you could!

Commands: Having access to calling JupyterLab/lumino commands at different stages would further reduce the amount of coding required to put together a really interesting tour. Perhaps being able to match and dispatch commands from the argument to callback would be sufficient, e.g.

steps: ...
callback:
- on:
    step: 0
    type: step:after
  command:
    id: some-ext:some-command
    args:
      some: arg

Anyhow, food for thought!

[fcollonval]

Thanks @bollwyvl for all the nice suggestions.

[bollwyvl]

Here's a rough automated cut of the top-level schema:

https://gist.github.com/bollwyvl/625e6c0473bbf058cf4c6fa8dfb1ec46

That JSON can be posted right into the playground.

Doing it "right" would take a fair amount of work, but this at least demonstrates the rough shape of what it might look like.

[fcollonval]

Awesome, thanks @bollwyvl for the gist (and the tip on ts-json-schema-generator 😉 ).

[fcollonval]

f98a074 introduced a command jupyterlab-tour:add to easily add a tour. The arguments accepted is quite restricted for now but enough for simple tour.

[bollwyvl]

Very cool!

[bollwyvl]

Looks great on binder! Have some other, unrelated thoughts: will raise more issues!

[fcollonval]

I just released a new version of jupyter_conda using that new feature 😉

And the binder image is available for testing: https://mybinder.org/v2/gh/fcollonval/jupyter_conda/master?urlpath=lab

[bollwyvl]

Will check it out!

An aside: that's awesome you're using mamba in jupyter_conda... it's way closer to interactive speed, and has some pretty nice additional features. I mean, you still need threadpoolexecutors, etc. as it didn't magically solve some of conda's larger one-at-a-time issues, but it comes back so much faster, it's not even funny. And it might be coming soon, natively, to a binder near you!

Bringing it back on-topic for this issue: I hope some machine-readable specs come out of some of the community work... I worked on some more formalized file specs for env.yml, meta.yml, construct.yml, anaconda-project.yml etc. but haven't released them. They would make some of these things way better to write alternate tooling that overcomes some of the persistent first-party UI fails. For example, such specs could be used to deliver conda language server support: eventually getting to know the text format (with autocomplete, introspection, and linting) vastly exceeds the power and accessibility that a pointy-clicky GUI can deliver, no matter how pretty. But keep up the good work!