📚 Minor improvements to docs (#670)

chrisjsewell · web-flow · commit ebb5b9f4e542 · 2023-01-06T18:52:32.000+01:00
diff --git a/docs/docutils.md b/docs/docutils.md
@@ -35,6 +35,10 @@ The commands are based on the [Docutils Front-End Tools](https://docutils.source
 ```
 :::
 
+:::{versionadded} 0.19.0
+`myst-suppress-warnings` replicates the functionality of sphinx's [`suppress_warnings`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings) for `myst.` warnings in the `docutils` CLI.
+:::
+
 The CLI commands can also utilise the [`docutils.conf` configuration file](https://docutils.sourceforge.io/docs/user/config.html) to configure the behaviour of the CLI commands. For example:
 
 ```
diff --git a/docs/faq/index.md b/docs/faq/index.md
@@ -142,7 +142,7 @@ See the [](syntax/header-anchors) section of extended syntaxes.
 :::
 
 If you'd like to *automatically* generate targets for each of your section headers,
-check out the [`autosectionlabel`](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html)
+check out the {external+sphinx:std:doc}`autosectionlabel <usage/extensions/autosectionlabel>`
 sphinx feature. You can activate it in your Sphinx site by adding the following to your
 `conf.py` file:
 
@@ -179,7 +179,7 @@ Moved to [](myst-warnings)
 ### Sphinx-specific page front matter
 
 Sphinx intercepts front matter and stores them within the global environment
-(as discussed [in the deflists documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html)).
+(as discussed in the {external+sphinx:std:doc}`sphinx documentation <usage/restructuredtext/field-lists>`.
 There are certain front-matter keys (or their translations) that are also recognised specifically by docutils and parsed to inline Markdown:
 
 - `author`
diff --git a/docs/intro.md b/docs/intro.md
@@ -28,7 +28,7 @@ conda install -c conda-forge myst-parser
 (intro/sphinx)=
 ## Enable MyST in Sphinx
 
-To get started with Sphinx, see their [Quickstart Guide](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
+To get started with Sphinx, see their {external+sphinx:std:doc}`quick-start guide <usage/quickstart>`.
 
 To use the MyST parser in Sphinx, simply add the following to your `conf.py` file:
 
diff --git a/docs/syntax/optional.md b/docs/syntax/optional.md
@@ -13,6 +13,7 @@ myst:
       :width: 200px
       ```
     key4: example
+    confpy: sphinx `conf.py` {external+sphinx:std:doc}`configuration file <usage/configuration>`
 ---
 
 (syntax/extensions)=
@@ -53,12 +54,12 @@ myst_enable_extensions = [
 
 ## Typography
 
-Adding `"smartquotes"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically convert standard quotations to their opening/closing variants:
+Adding `"smartquotes"` to `myst_enable_extensions` (in the {{ confpy }}) will automatically convert standard quotations to their opening/closing variants:
 
 - `'single quotes'`: 'single quotes'
 - `"double quotes"`: "double quotes"
 
-Adding `"replacements"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically convert some common typographic texts
+Adding `"replacements"` to `myst_enable_extensions` (in the {{ confpy }}) will automatically convert some common typographic texts
 
 text  | converted
 ----- | ----------
@@ -95,7 +96,7 @@ and you will need to suppress the `myst.strikethrough` warning
 (syntax/math)=
 ## Math shortcuts
 
-Math is parsed by adding to the `myst_enable_extensions` list option, in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html) one or both of:
+Math is parsed by adding to the `myst_enable_extensions` list option, in the {{ confpy }} one or both of:
 
 - `"dollarmath"` for parsing of dollar `$` and `$$` encapsulated math.
 - `"amsmath"` for direct parsing of [amsmath LaTeX environments](https://ctan.org/pkg/amsmath).
@@ -230,7 +231,7 @@ See [the extended syntax option](syntax/amsmath).
 (syntax/mathjax)=
 ### Mathjax and math parsing
 
-When building HTML using the [sphinx.ext.mathjax](https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax) extension (enabled by default),
+When building HTML using the {external+sphinx:mod}`sphinx.ext.mathjax <sphinx.ext.mathjax>` extension (enabled by default),
 If `dollarmath` is enabled, Myst-Parser injects the `tex2jax_ignore` (MathJax v2) and  `mathjax_ignore` (MathJax v3) classes in to the top-level section of each MyST document, and adds the following default MathJax configuration:
 
 MathJax version 2 (see [the tex2jax preprocessor](https://docs.mathjax.org/en/v2.7-latest/options/preprocessors/tex2jax.html#configure-tex2jax):
@@ -252,7 +253,7 @@ To change this behaviour, set a custom regex, for identifying HTML classes to pr
 (syntax/linkify)=
 ## Linkify
 
-Adding `"linkify"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will automatically identify "bare" web URLs and add hyperlinks:
+Adding `"linkify"` to `myst_enable_extensions` (in the {{ confpy }}) will automatically identify "bare" web URLs and add hyperlinks:
 
 `www.example.com` -> www.example.com
 
@@ -267,7 +268,7 @@ Either directly; `pip install linkify-it-py` or *via* `pip install myst-parser[l
 
 ## Substitutions (with Jinja2)
 
-Adding `"substitution"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)) will allow you to add substitutions, added in either the `conf.py` using `myst_substitutions`:
+Adding `"substitution"` to `myst_enable_extensions` (in the {{ confpy }}) will allow you to add substitutions, added in either the `conf.py` using `myst_substitutions`:
 
 ```python
 myst_substitutions = {
@@ -352,7 +353,7 @@ This may lead to unexpected outcomes.
 
 :::
 
-Substitution references are assessed as [Jinja2 expressions](http://jinja.palletsprojects.com) which can use [filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters), and also contains the [Sphinx Environment](https://www.sphinx-doc.org/en/master/extdev/envapi.html) in the context (as `env`).
+Substitution references are assessed as [Jinja2 expressions](http://jinja.palletsprojects.com) which can use [filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-builtin-filters), and also contains the {external+sphinx:std:doc}`Sphinx Environment <extdev/envapi>` in the context (as `env`).
 Therefore you can do things like:
 
 ```md
@@ -400,7 +401,7 @@ However, since Jinja2 substitutions allow for Python methods to be used, you can
 
 ## Code fences using colons
 
-By adding `"colon_fence"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"colon_fence"` to `myst_enable_extensions` (in the {{ confpy }}),
 you can also use `:::` delimiters to denote code fences, instead of ```` ``` ````.
 
 Using colons instead of back-ticks has the benefit of allowing the content to be rendered correctly, when you are working in any standard Markdown editor.
@@ -537,7 +538,7 @@ $ myst-anchors -l 2 docs/syntax/optional.md
 
 ## Definition Lists
 
-By adding `"deflist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"deflist"` to `myst_enable_extensions` (in the {{ confpy }}),
 you will be able to utilise definition lists.
 Definition lists utilise the [markdown-it-py deflist plugin](markdown_it:md/plugins), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
 
@@ -616,7 +617,7 @@ Term 3
 (syntax/tasklists)=
 ## Task Lists
 
-By adding `"tasklist"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"tasklist"` to `myst_enable_extensions` (in the {{ confpy }}),
 you will be able to utilise task lists.
 Task lists utilise the [markdown-it-py tasklists plugin](markdown_it:md/plugins),
 and are applied to markdown list items starting with `[ ]` or `[x]`:
@@ -725,7 +726,7 @@ Currently `sphinx.ext.autodoc` does not support MyST, see [](howto/autodoc).
 (syntax/attributes)=
 ## Inline attributes
 
-By adding `"attrs_inline"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"attrs_inline"` to `myst_enable_extensions` (in the {{ confpy }}),
 you can enable parsing of inline attributes after certain inline syntaxes.
 This is adapted from [djot inline attributes](https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#inline-attributes),
 and also related to [pandoc bracketed spans](https://pandoc.org/MANUAL.html#extension-bracketed_spans).
@@ -844,7 +845,7 @@ This is usually a bad option, because the HTML is treated as raw text during the
 
 HTML parsing to the rescue!
 
-By adding `"html_image"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"html_image"` to `myst_enable_extensions` (in the {{ confpy }}),
 MySt-Parser will attempt to convert any isolated `img` tags (i.e. not wrapped in any other HTML) to the internal representation used in sphinx.
 
 ```html
@@ -866,7 +867,7 @@ I'm an inline image: <img src="img/fun-fish.png" height="20px">
 
 ## Markdown Figures
 
-By adding `"colon_fence"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"colon_fence"` to `myst_enable_extensions` (in the {{ confpy }}),
 we can combine the above two extended syntaxes,
 to create a fully Markdown compliant version of the `figure` directive named `figure-md`.
 
@@ -908,7 +909,7 @@ As we see here, the target we set can be referenced:
 
 ## HTML Admonitions
 
-By adding `"html_admonition"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"html_admonition"` to `myst_enable_extensions` (in the {{ confpy }}),
 you can enable parsing of `<div class="admonition">` HTML blocks.
 These blocks will be converted internally to Sphinx admonition directives, and so will work correctly for all output formats.
 This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
@@ -974,7 +975,7 @@ You can also nest HTML admonitions:
 
 ## Direct LaTeX Math
 
-By adding `"amsmath"` to `myst_enable_extensions` (in the sphinx `conf.py` [configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html)),
+By adding `"amsmath"` to `myst_enable_extensions` (in the {{ confpy }}),
 you can enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations.
 These top-level math environments will then be directly parsed:
 
diff --git a/docs/syntax/roles-and-directives.md b/docs/syntax/roles-and-directives.md
@@ -5,7 +5,12 @@
 Roles and directives provide a way to extend the syntax of MyST in an unbound manner,
 by interpreting a chuck of text as a specific type of markup, according to its name.
 
-Mostly all [docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html), [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html), [sphinx roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html), or [sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) can be used in MyST.
+Mostly all
+[docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html),
+[docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html),
+{external+sphinx:std:doc}`Sphinx roles <usage/restructuredtext/roles>`, or
+{external+sphinx:std:doc}`Sphinx directives <usage/restructuredtext/directives>`
+can be used in MyST.
 
 ## Syntax
 
diff --git a/docs/syntax/syntax.md b/docs/syntax/syntax.md
@@ -85,7 +85,7 @@ would be equivalent to:
 ### Setting HTML Metadata
 
 The front-matter can contain the special key `html_meta`; a dict with data to add to the generated HTML as [`<meta>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta).
-This is equivalent to using the [RST `meta` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#html-metadata).
+This is equivalent to using the {external+sphinx:ref}`meta directive <html-meta>`.
 
 HTML metadata can also be added globally in the `conf.py` *via* the `myst_html_meta` variable, in which case it will be added to all MyST documents.
 For each document, the `myst_html_meta` dict will be updated by the document level front-matter `html_meta`, with the front-matter taking precedence.
@@ -257,7 +257,8 @@ Target headers are defined with this syntax:
 (header_target)=
 ```
 
-They can then be referred to with the [ref inline role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref):
+They can then be referred to with the
+{external+sphinx:ref}`ref inline role <ref-role>`:
 
 ```md
 {ref}`header_target`
@@ -277,7 +278,7 @@ Alternatively using the markdown syntax:
 [my text](header_target)
 ```
 
-is equivalent to using the [any inline role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-any):
+is equivalent to using the {external+sphinx:ref}`any inline role <any-role>`:
 
 ```md
 {any}`my text <header_target>`
diff --git a/myst_parser/inventory.py b/myst_parser/inventory.py
@@ -320,6 +320,12 @@ def inventory_cli(inputs: None | list[str] = None):
         metavar="NAME",
         help="Filter the inventory by reference name pattern",
     )
+    parser.add_argument(
+        "-l",
+        "--loc",
+        metavar="LOC",
+        help="Filter the inventory by reference location pattern",
+    )
     parser.add_argument(
         "-f",
         "--format",
@@ -363,6 +369,15 @@ def inventory_cli(inputs: None | list[str] = None):
                     if fnmatchcase(n, args.name)
                 }
 
+    if args.loc:
+        for domain in invdata["objects"]:
+            for otype in list(invdata["objects"][domain]):
+                invdata["objects"][domain][otype] = {
+                    n: i
+                    for n, i in invdata["objects"][domain][otype].items()
+                    if fnmatchcase(i["loc"], args.loc)
+                }
+
     # clean up empty items
     for domain in list(invdata["objects"]):
         for otype in list(invdata["objects"][domain]):
diff --git a/tests/test_inventory.py b/tests/test_inventory.py
@@ -37,7 +37,9 @@ def test_inv_filter_fnmatch(data_regression):
     data_regression.check(output)
 
 
-@pytest.mark.parametrize("options", [(), ("-d", "std"), ("-o", "doc"), ("-n", "ref")])
+@pytest.mark.parametrize(
+    "options", [(), ("-d", "std"), ("-o", "doc"), ("-n", "ref"), ("-l", "index.html*")]
+)
 def test_inv_cli_v2(options, capsys, file_regression):
     inventory_cli([str(STATIC / "objects_v2.inv"), "-f", "yaml", *options])
     text = capsys.readouterr().out.strip() + "\n"
diff --git a/tests/test_inventory/test_inv_cli_v2_options4_.yaml b/tests/test_inventory/test_inv_cli_v2_options4_.yaml
@@ -0,0 +1,12 @@
+name: Python
+version: ''
+objects:
+  std:
+    label:
+      ref:
+        loc: index.html#ref
+        text: Title
+    doc:
+      index:
+        loc: index.html
+        text: Title
