From 2eccdb04f35e2b79163bf680fe9c7a6f8daef926 Mon Sep 17 00:00:00 2001 From: Angus Hollands Date: Wed, 21 Aug 2024 15:23:26 +0100 Subject: [PATCH] docs: update usage information --- README.md | 10 ++++++++-- docs/extend-sphinx.md | 4 ++-- docs/include-sphinx.md | 4 ++-- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index d6e4c3a..b43bfe6 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ in order to be able to use the `myst` builder, e.g. sphinx-build -b myst . ``` -The generated `.myst.json` files in `/content` can be added to your TOC e.g. using a `pattern` entry, e.g. +The generated `.myst.json` files in `` can be added to your TOC e.g. using a `pattern` entry, e.g. ```yaml project: @@ -27,7 +27,13 @@ project: ``` -You can also serve the `myst.xref.json` from your Sphinx deployment to enable MyST xrefs. +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 . +``` +will generate a `myst.xref.json` in ``. The contents of `` should be added to your site's root directory. > [!WARNING] > This extension is a literal work-in-progress; some things don't work. diff --git a/docs/extend-sphinx.md b/docs/extend-sphinx.md index 23404f4..8a500a1 100644 --- a/docs/extend-sphinx.md +++ b/docs/extend-sphinx.md @@ -14,13 +14,13 @@ The Sphinx `conf.py` for your project should include `sphinx-ext-mystmd`. If you extensions = [ "sphinx_ext_mystmd" ] -html_extra_path = ["./myst-build"] +html_extra_path = ["./myst-xrefs"] ::: ## Build the MyST Metadata ```shell -sphinx-build -b myst . ./myst-build +sphinx-build -b myst-xref . ./myst-xrefs ``` ## Build the HTML Deployment diff --git a/docs/include-sphinx.md b/docs/include-sphinx.md index 6aaaeec..8205de5 100644 --- a/docs/include-sphinx.md +++ b/docs/include-sphinx.md @@ -19,7 +19,7 @@ extensions = [ ## Build the Sphinx Project ```shell -sphinx-build -b myst sphinx myst-build +sphinx-build -b myst sphinx myst-asts ``` ## Configure the MyST Project @@ -31,7 +31,7 @@ version: 1 project: toc: - file: index.md - - pattern: myst-build/content/**.myst.json + - pattern: myst-asts/content/**.myst.json site: template: book-theme :::