✨ Add extends field to myst.yml for composing multiple yamls

[fwkoch]

This PR allows users to have project frontmatter defined in multiple files (all of the same myst.yml format), then the main myst.yml can bring in those other files under the top level extends key. A small example has been added to the docs.

[stevejpurves]

looks good! would perhaps just add some tests around existing Page->Project frontmatter inheritance, since the function that was doing that previously looks like it has been made generic? and is now doing Project->Project as well as Page->Project filling...

[choldgraf]

If the TOC PR gets in before this one is finished:

• 📥 Load TOC from toc entry #1188

I'd recommend using that as an example here. I think a common use-case will be to have a separate toc.yml file and use this feature to bring it in (for communities that have a lot of TOC content and thus don't want to have to scroll through a huge list of pages in their config file)

[fwkoch]

That makes sense - I'll update, depending on the order these come in...

I also suspect we will be scattering this all around the docs. E.g. where we talk about math macros, we can say "reference external macros by..." and where we talk about the toc, "reference external toc by..." etc. So hopefully this one little section won't be the only mention in the docs, long term.

[choldgraf]

Could this be a subsection instead of a note? That way it is easier to discover in the table of contents

[choldgraf]

Does this work for externally-defined .yml files? (e.g. in a different github repository?)

If not, then would it be possible to download external files locally as part of the build process in a way that would work as expected here?

[fwkoch]

Currently the files must be available locally, from a relative path at build-time (they can be outside the MyST project).

I agree we should be able to also put a url here, e.g.:

extends:
  - https://example.com/my-other-myst.yml

We get into a discussion of this over here: #336

But I think the url download/caching is a separate (smaller) PR.

[agoose77]

I was just thinking of looking at this in the coming week. How exciting!!!