docs: update usage information

README.md

@@ -15,7 +15,7 @@ in order to be able to use the `myst` builder, e.g.
 sphinx-build -b myst . <BUILDDIR>
 ```
 
-The generated `.myst.json` files in `<BUILDDIR>/content` can be added to your TOC e.g. using a `pattern` entry, e.g.
+The generated `.myst.json` files in `<BUILDDIR>` 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 . <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.

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

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
 :::