Serve theme documentation from this repository and add PR previews

[choldgraf]

Currently, we store the documentation for our bundled myst themes in the mystmd repository. The documentation in this repository is a demo site of components for references.

By having the documentation for the theme in a separate repository, we have a few downsides:

• Changes in functionality to this theme will require changes to documentation in a different space (mystmd.org).
• Changes in functionality to this theme aren't easily previewed in PRs, because no local documentation is built as a preview.

I propose that we do the following things:

• move all documentation that is related to the bundled myst themes into this repository (in docs/)
• move the components site to a sub-directory like docs/components/
• add a netlify PR preview for the documentation that uses the latest theme build in this repository
• keep templating/theme documentation in mystmd if it is about web templating in general, and not these themes specifically.
• embed the documentation for these themes into the mystmd.org docs so that it functionally looks the same that it does now (perhaps with "myst default themes" having a dedicated page)

[agoose77]

I think you've identified some good points of improvement for our two-repo ecosystem. At the heart of this issue is the fact that we have three kinds of documentation:

• MyST documentation (CLI)
• MyST theme documentation
• MyST theme component documentation

The problems we need to solve are:

We're currently taking the approach that most users should just go to mystmd.org for documentation in this ecosystem -- a departure from the JB1 approach which has docs split around the ecosystem. That introduces two problems; fragmentation and repetition of information and fragmentation of resources (i.e. multiple sites in your search engine). However, this does mean that the coupling between components in terms of where the code lives is not so obvious.

So, my summary of the problems we need to solve in this space is:

1. We should not bless our own web themes too much; we want it to be obvious that developers can add their own and users can look for them.
2. We should have theme component documentation (Storybook)
3. We should make it possible to preview changes to our theme components
4. We should have documentation on our pre-designed themes
5. We should make it possible to preview changes to our pre-designed themes

It might not be super easy to solve all of these; there may be some trade-offs. But, I'll take a stab at something and see where we end up.

[choldgraf]

Just noting that I generally agree with all of the above, and: I suggest that we take an MVP approach here. For example if moving the docs over here would be complicated, it could be helpful to at least run a docs preview in our PRs of the mystmd.org/guide docs that use the latest assets in this repository so that we can see things. Then we could decide/deal with moving documentation later.

[agoose77]

@choldgraf took the words right out of my mouth! I think this is actually the right step; figuring out the higher level changes will probably need to wait until the rest of the team are present.