Metadata-Version: 2.3
Name: sphinx-ext-mystmd
Version: 0.0.0
Summary: A Sphinx extension to build MyST-MD AST from a Sphinx project
Project-URL: Documentation, https://github.com/executablebooks/sphinx-ext-mystmd#readme
Project-URL: Issues, https://github.com/executablebooks/sphinx-ext-mystmd/issues
Project-URL: Source, https://github.com/executablebooks/sphinx-ext-mystmd
Author-email: Angus Hollands <goosey15@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sphinx-ext-mystmd

A Sphinx extension to build MyST-MD AST from a Sphinx project. This can be used for:

1. Embedding API documentation in a MyST project
2. Providing MyST xref support for a deployed Sphinx project (gradual transition)

Add this extension to your `conf.py` e.g.
```python
extensions = ["sphinx_ext_mystmd"]
```
in order to be able to use the `myst` builder, e.g.

```shell
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.

```yaml
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
```shell
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.
