A Sphinx extension to build MyST-MD AST from a Sphinx project. This can be used for:
- Embedding API documentation in a MyST project
- Providing MyST xref support for a deployed Sphinx project (gradual transition)
Add this extension to your conf.py e.g.
extensions = ["sphinx_ext_mystmd"]in order to be able to use the myst builder, e.g.
sphinx-build -b myst . <BUILDDIR>The generated .myst.json files in <BUILDDIR> can be added to your TOC e.g. using a pattern entry, e.g.
project:
toc:
- file: index.md
- title: Sphinx Build
children:
- pattern: <BUILDDIR>/**.myst.json
You can also build an xref distribution for your site, which allows MyST projects to richly cross-reference into your documentation.
Running
sphinx-build -b myst-xref . <BUILDDIR>will generate a myst.xref.json in <BUILDDIR>. The contents of <BUILDDIR> should be added to your site's root directory.
Warning
This extension is a literal work-in-progress; some things don't work. The intention is to get something on the page before we finalize it.