♻️ REFACTOR: docs example directive via sphinx-syntax-example (#1181)

Author: chrisjsewell

.pre-commit-config.yaml

@@ -37,6 +37,7 @@ repos:
       - sphinx~=8.2
       - markdown-it-py~=4.2
       - mdit-py-plugins~=0.6.0
+      - sphinx-syntax-example~=0.2.0
       files: >
         (?x)^(
             myst_parser/.*py|

docs/_static/local.css

@@ -9,21 +9,24 @@ h1:not(.rubric) {
     text-decoration: underline;
 }
 
-/** MyST examples */
-.myst-example {
+/** Syntax examples */
+.syntax-example {
     border: 1px solid var(--pst-color-border);
     border-left-color: var(--pst-color-info);
     border-left-width: .2em;
     box-shadow: rgba(0, 0, 0, 0.25) 0px 5px 15px;
     margin-bottom: 1rem;
 }
-.myst-example-source > div[class*="highlight-"]{
+/* The source pane *is* the highlight-<lang> div (not a wrapper around one),
+   so zero its margin here to keep it flush inside the frame.
+   local.css loads last, so this wins. */
+.syntax-example > .syntax-example-source {
     margin: 0;
 }
-.myst-example-render {
+.syntax-example-render {
     padding: 0.5rem;
 }
-.myst-example-render > :first-child {
+.syntax-example-render > :first-child {
     margin-top: 0.5rem;
 }
 

docs/conf.py

@@ -223,19 +223,21 @@ def setup(app: Sphinx):
         DocutilsCliHelpDirective,
         MystAdmonitionDirective,
         MystConfigDirective,
-        MystExampleDirective,
         MystLexer,
         MystToHTMLDirective,
         MystWarningsDirective,
         NumberSections,
         StripUnsupportedLatex,
+        SyntaxExampleDocsDirective,
     )
 
     app.add_directive("myst-config", MystConfigDirective)
     app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)
     app.add_directive("doc-directive", DirectiveDoc)
     app.add_directive("myst-warnings", MystWarningsDirective)
-    app.add_directive("myst-example", MystExampleDirective)
+    # NOTE: if `sphinx_syntax_example` is ever added to `extensions` (e.g. to pick
+    # up its stylesheet), drop this line too — it registers the same directive.
+    app.add_directive("syntax-example", SyntaxExampleDocsDirective)
     app.add_directive("myst-admonitions", MystAdmonitionDirective)
     app.add_directive("myst-to-html", MystToHTMLDirective)
     app.add_post_transform(StripUnsupportedLatex)

docs/intro.md

@@ -147,7 +147,7 @@ extensions = [
 
 Now, we can use the `design` directive to add a web-component to our Markdown file!
 
-::::{myst-example}
+::::{syntax-example}
 :::{card} Card Title
 Header
 ^^^
@@ -158,7 +158,7 @@ Footer
 ::::
 
 
-::::::{myst-example}
+::::::{syntax-example}
 
 ::::{tab-set}
 
@@ -196,7 +196,7 @@ Content 2
 % Now, add a **mermaid directive** to your Markdown file.
 % For example:
 
-% :::{myst-example}
+% :::{syntax-example}
 % Here's a cool mermaid diagram!
 %
 % ```{mermaid}

docs/syntax/admonitions.md

@@ -10,7 +10,7 @@ The [alert extension](syntax/alerts) provides GitHub-style alerts as a lightweig
 Admonitions are a special case of {{directive}} extensions.
 It is advised to use admonitions with the [colon_fence](#syntax/colon_fence) extension, which signify that the content of the block is also MyST Markdown.
 
-::::{myst-example}
+::::{syntax-example}
 
 :::{tip}
 Let's give readers a helpful hint!
@@ -30,7 +30,7 @@ These admonitions take no argument, but may be specified with options:
 :class: A space-separated list of CSS classes to add to the admonition, conforming to the [identifier normalization rules](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization).
 :name: A reference target for the admonition (see [cross-referencing](#syntax/referencing)).
 
-::::{myst-example}
+::::{syntax-example}
 
 :::{tip}
 :class: myclass1 myclass2
@@ -44,7 +44,7 @@ Let's give readers a helpful hint!
 
 Sphinx also adds a number of additional admonition types, for denoting changes to the documentation, or to the codebase:
 
-::::{myst-example}
+::::{syntax-example}
 
 :::{versionadded} 1.2.3
 Explanation of the new feature.
@@ -66,7 +66,7 @@ To provide a custom title for an admonition, use the `admonition` directive.
 If you also want to style the admonition as one of the core admonition types,
 you can use the `admonition` directive with the `class` option.
 
-::::{myst-example}
+::::{syntax-example}
 
 :::{admonition} My custom title with *Markdown*!
 :class: tip
@@ -80,7 +80,7 @@ This is a custom title for a tip admonition.
 
 The [sphinx-togglebutton](https://sphinx-togglebutton.readthedocs.io) extension allows you to create collapsible admonitions, by adding a `dropdown` class to the admonition.
 
-::::{myst-example}
+::::{syntax-example}
 
 :::{note}
 :class: dropdown
@@ -97,7 +97,7 @@ without it taking up too much space on the page.
 Using the [colon_fence](#syntax/colon_fence) extension,
 content block can be wrapped in containers with a custom CSS class.
 
-::::{myst-example}
+::::{syntax-example}
 :::bg-primary
 This is a container with a custom CSS class.
 
@@ -108,7 +108,7 @@ This is a container with a custom CSS class.
 Using the [sphinx-design](https://github.com/executablebooks/sphinx-design) extension,
 it is also possible to create beautiful, screen-size responsive web-components.
 
-::::{myst-example}
+::::{syntax-example}
 :::{card} Card Title
 Header
 ^^^
@@ -119,7 +119,7 @@ Footer
 ::::
 
 
-::::::{myst-example}
+::::::{syntax-example}
 
 ::::{tab-set}
 

docs/syntax/code_and_apis.md

@@ -6,7 +6,7 @@
 Code blocks contain a language identifier, which is used to determine the language of the code.
 This language is used to determine the syntax highlighting, using an available [pygments lexer](https://pygments.org/docs/lexers/).
 
-:::{myst-example}
+:::{syntax-example}
 ```python
 from a import b
 c = "string"
@@ -27,7 +27,7 @@ you can do so by nesting them in backticks of a greater length.
 Markdown will treat the outer-most backticks as the edges of the "raw" block and everything inside will show up.
 For example:
 
-:::{myst-example}
+:::{syntax-example}
 `` `hi` ``
 
 ````
@@ -43,7 +43,7 @@ hi
 
 The [attrs_inline](#syntax/attributes/inline) extension can be used to apply syntax highlighting to inline code:
 
-:::{myst-example}
+:::{syntax-example}
 Inline Python code `a = "b"`{l=python}
 :::
 
@@ -59,7 +59,7 @@ myst_number_code_blocks = ["typescript"]
 
 Will number all code blocks with the `typescript` lexer by default.
 
-:::{myst-example}
+:::{syntax-example}
 ```typescript
 type MyBool = true | false;
 
@@ -73,7 +73,7 @@ interface User {
 To apply numbering and highlighting to a specific code block,
 the [attrs_block](#syntax/attributes/block) extension can be used:
 
-:::{myst-example}
+:::{syntax-example}
 {lineno-start=1 emphasize-lines="2,3"}
 ```python
 a = 1
@@ -87,7 +87,7 @@ c = 3
 With the `code-block` {{directive}},
 a caption can be added to a code blocks, as well as other options:
 
-:::{myst-example}
+:::{syntax-example}
 ```{code-block} python
 :caption: This is a caption
 :emphasize-lines: 2,3
@@ -136,7 +136,7 @@ The [Sphinx documentation](inv:sphinx#code-block)
 
 Longer pieces of code can be included from files using the `literalinclude` {{directive}}:
 
-:::{myst-example}
+:::{syntax-example}
 ```{literalinclude} examples/example.py
 ```
 :::
@@ -145,7 +145,7 @@ The file name is usually relative to the current file’s path. However, if it i
 
 To select only a sub-section of the file, the `lines`, `pyobject` or `start-after` and `end-before` options can be used:
 
-:::{myst-example}
+:::{syntax-example}
 ```{literalinclude} examples/example.py
 :start-after: start example
 :end-before: end example
@@ -175,7 +175,7 @@ As opposed to `sphinx.ext.autodoc`, `sphinx-autodoc2` performs static (rather th
 Alternatively, the `autodoc2-object` directive can be used to generate documentation for a single object.
 To embed in a MyST document the MyST `render_plugin` should be specified, for example:
 
-````{myst-example}
+````{syntax-example}
 ```{autodoc2-object} myst_parser.sphinx_ext.main.setup_sphinx
 render_plugin = "myst"
 no_index = true
@@ -184,14 +184,14 @@ no_index = true
 
 This can be referenced elsewhere in the document using the `:py:obj:` role, or a `#` link (see [cross-referencing](#syntax/referencing)).
 
-````{myst-example}
+````{syntax-example}
 - {py:obj}`myst_parser.sphinx_ext.main.setup_sphinx`
 - [](#myst_parser.sphinx_ext.main.setup_sphinx)
 ````
 
 Additionally, summaries of multiple objects can be generated using the `autodoc2-summary` directive:
 
-````{myst-example}
+````{syntax-example}
 ```{autodoc2-summary}
 :renderer: myst
 
@@ -215,7 +215,7 @@ autodoc2_docstring_parser_regexes = [
 
 For example:
 
-````{myst-example}
+````{syntax-example}
 ```{autodoc2-object} myst_parser.setup
 render_plugin = "myst"
 no_index = true
@@ -231,7 +231,7 @@ docstring_parser_regexes = [
 [Sphinx extension `autodoc`](inv:sphinx#sphinx.ext.autodoc) also can generate documentation for Python objects.
 However, because it is hard-coded to generate RestructureText, the special [`eval-rst` directive](#syntax/directives/parsing) needs to be used:
 
-````{myst-example}
+````{syntax-example}
 ```{eval-rst}
 .. autofunction:: myst_parser.sphinx_ext.main.setup_sphinx
     :noindex:
@@ -240,7 +240,7 @@ However, because it is hard-coded to generate RestructureText, the special [`eva
 
 Summaries can also be generated with [`autosummary`](inv:sphinx#sphinx.ext.autosummary):
 
-````{myst-example}
+````{syntax-example}
 ```{eval-rst}
 .. autosummary::
     :nosignatures:

docs/syntax/cross-referencing.md

@@ -23,7 +23,7 @@ primary HTML id, used by tocs, permalinks and `objects.inv`; the implicit
 heading id is kept as a secondary anchor, so existing fragment links keep working.
 ```
 
-::::{myst-example}
+::::{syntax-example}
 
 (heading-target)=
 ### Heading
@@ -47,7 +47,7 @@ This is a directive with a `name` option
 There are also other ways to create targets, specific to certain directives,
 such as [glossaries](#syntax/glossaries) create targets for terms, and [code APIs](#syntax/apis) create targets for objects:
 
-::::{myst-example}
+::::{syntax-example}
 {.glossary}
 my other term
 : Definition of the term
@@ -79,7 +79,7 @@ By default the anchor "slugs" are created according to the [GitHub implementatio
 
 For example, using `myst_heading_anchors = 2`:
 
-::::{myst-example}
+::::{syntax-example}
 ## A heading with slug
 
 ## A heading with slug
@@ -191,7 +191,7 @@ Otherwise, the link text will be the destination itself.
 
 #### Autolinks
 
-:::{myst-example}
+:::{syntax-example}
 
 :External URL: <https://example.com>
 :Internal target reference: <project:#cross-references>
@@ -204,7 +204,7 @@ Otherwise, the link text will be the destination itself.
 
 #### Inline links with implicit text
 
-:::{myst-example}
+:::{syntax-example}
 
 :External URL: [](https://example.com)
 :Internal target reference: [](#cross-references)
@@ -217,7 +217,7 @@ Otherwise, the link text will be the destination itself.
 
 #### Inline links with explicit text
 
-:::{myst-example}
+:::{syntax-example}
 
 :External URL: [Explicit text](https://example.com)
 :Internal target reference: [Explicit text](#cross-references)
@@ -389,7 +389,7 @@ Sphinx offers numerous [roles for referencing](#usage/restructuredtext/roles) sp
 
 These can also be used within MyST documents, although it is recommended to use the Markdown syntax where possible, which is more portable and native to MyST.
 
-:::{myst-example}
+:::{syntax-example}
 Sphinx roles:
 
 - {ref}`syntax/referencing`, {ref}`Explicit text <syntax/referencing>`