➕ Add myst:template directive for documentation

[choldgraf]

There's a hand-coded table of theme options, but the options have changed since it was written. This adds a little code-cell that pulls the latest YAML for each theme's configuration, and inserts it as a pandas table. This PR adds a new myst:template directive that pulls in the template information from https://api.mystmd.org.

It is current pretty simplistic, in a future iteration we could parse the output as markdown but that's blocked on:

This also documents the site.actions and site.nav options, since those exist but aren't documented anywhere.

[rowanc1]

Super cool!

[choldgraf]

Can you think of a way to attach a label to each? Then we could embed each in their own table w a header

[choldgraf]

Oh maybe the easiest would be to split that into a function and call it twice. I can't find a way to attach multiple labels to outputs of a cell.

Makes me wonder if it could be useful to support something like multiple labels comments in a cell, and if found we attach them to cell outputs sequentially

[choldgraf]

Now reusing a function with 3 cells in total, so that we can separate out the themes into sections. I think this is good to go as an incremental improvement...

[rowanc1]

If we do it through a plugin, then this could be full, parsed mdast as well. With labels etc.

[choldgraf]

Could you explain more what you mean by a plugin? Parsing these as mdast is exactly what I want. I am just a lot more comfortable with python than JavaScript

[choldgraf]

One more update: I've documented site.actions and site.options.

I had a non-blocking question come up as I was doing this:

What is the difference between site.options.foo, and site.nav + site.actions? Are nav and actions special keys that are treated differently from site.options? Why aren't they nested under site.options?

[agoose77]

Could you explain more what you mean by a plugin? Parsing these as mdast is exactly what I want. I am just a lot more comfortable with python than JavaScript

An example of a custom plugin used on https://mystmd.org is the myst:directive directive, which is used to provide documentation for directives.

We can use the same approach to implement a theme information role. Using @choldgraf's idea, I'll implement it as a plugin :)

[agoose77]

Ensure that all concurrent builds have access to this at the same time by setting the global promise before resolving it.

[choldgraf]

I think that the rendered table looks nice @agoose77 ! What are the benefits of doing this via a mystmd plugin vs. doing this via Python? Is the main improvement that we get a proper structured table? Or is this something we can re-use this plugin for in general? And would this be any different than if we had markdown parsing via #1026 ?

I added a quick commit to document to each of these plugins as examples of plugin syntax, btw. Maybe they'll be a helpful path to follow for people that want to learn how the plugin infrastructure works.

@agoose77 any chance you could add some comments to the plugin so that others could use it as a learning guide?

Either way, I'd suggest that we just merge this in and iterate from there. @agoose77 or @fwkoch want to approve and then we can move forward?

[fwkoch]

This works great, and it's exciting to have another plugin example in the docs (as well as more explicit documentation about them)!

Regarding nav/actions vs options - I don't think there is anything too deep there, it was just a decision about what was common to all sites (top-level keys) vs. theme-specific (nested under options). Other top level keys I think are pretty universal to sites (title, subtitle, thumbnail, favicon, domains...), but I do see it's easy to argue that you could build a theme without nav or actions... I think that's ok, though - it's similar to, like, a tex template - you could make a tex template that ignores frontmatter.authors, but that doesn't mean authors should be an "option" rather than "frontmatter"

We are probably missing more documentation around what can be specified directly on the site... in addition to nav/actions there's quite a bit of other "site frontmatter" https://github.com/executablebooks/mystmd/blob/main/packages/myst-config/src/site/types.ts#L26-L33

[choldgraf]

Thanks for that explanation @fwkoch ! I've added a short explanation to the PR saying that other options might not be documented, and linked to two files that I think are relevant. We can flesh that out over time, but at least now the information is linked somewhere.

I think your reasoning about site.foo vs. site.options.foo makes sense, though I did find it a bit confusing that several top-level keys don't seem to have an impact on the book theme. For example site.banner didn't seem to do anything either.

It would be helpful if we raised a warning any time somebody specified a site.key that was not supported by the current theme.

[agoose77]

I think that the rendered table looks nice @agoose77 ! What are the benefits of doing this via a mystmd plugin vs. doing this via Python? Is the main improvement that we get a proper structured table? Or is this something we can re-use this plugin for in general? And would this be any different than if we had markdown parsing via #1026 ?

The main benefit is that we can use this plugin across multiple files using a directive -- no need to require an execution context and non-JS dependencies. It also feels more readable because it's a declarative inclusion rather than an imperative "use Pandas to parse options". As we get an AST, that is also nice (even though we can build ASTs from Jupyter outputs)!

I added a quick commit to document to each of these plugins as examples of plugin syntax, btw. Maybe they'll be a helpful path to follow for people that want to learn how the plugin infrastructure works.

Fantastic, what a great idea @choldgraf!

@agoose77 any chance you could add some comments to the plugin so that others could use it as a learning guide?

👍 I'll do that.

[choldgraf]

Sounds good! My feeling is that we can merge this one and iterate from there. @agoose77 do you wanna merge? Otherwise I'll do so later today since @fwkoch already approved

[agoose77]

Yep, merging now!