📚 DOCS: Add myst-example directive (#705)

Author: chrisjsewell

docs/_static/local.css

@@ -15,6 +15,21 @@ h3:not(.tippy-header)::before {
     content: counter(subsection) "." counter(subsubsection) ". ";
 }
 
+/** MyST examples */
+.myst-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-"]{
+    margin: 0;
+}
+.myst-example-render {
+    padding: 0.5rem;
+}
+
 /** No icon for admonitions with no-icon class */
 .admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {
     content: "";

docs/conf.py

@@ -33,6 +33,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx_design",
+    "sphinx_copybutton",
     "sphinxext.rediraffe",
     "sphinxcontrib.mermaid",
     "sphinxext.opengraph",
@@ -212,13 +213,15 @@ def setup(app: Sphinx):
         DirectiveDoc,
         DocutilsCliHelpDirective,
         MystConfigDirective,
+        MystExampleDirective,
         MystWarningsDirective,
     )
 
     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)
     app.add_post_transform(StripUnsupportedLatex)
     app.connect("html-page-context", add_version_to_css)
 

docs/syntax/syntax.md

@@ -157,15 +157,11 @@ myst:
 You may add comments by putting the `%` character at the beginning of a line. This will
 prevent the line from being parsed into the output document.
 
-For example, this code:
-
-```md
-% my comment
-```
-
-Is below, but it won't be parsed into the document.
+For example, this won't be parsed into the document:
 
+:::{myst-example}
 % my comment
+:::
 
 ````{important}
 Since comments are a block-level entity, they will terminate the previous block.
@@ -197,16 +193,12 @@ like [jupyter notebooks](https://jupyter.org/),
 to indicate a new text cell. It will not show up in the rendered text,
 but is stored in the internal document structure for use by developers.
 
-For example, this code:
+For example, this won't be parsed into the document:
 
-```md
+```{myst-example}
 +++ some text
 ```
 
-Is below, but it won't be parsed into the document.
-
-+++
-
 (syntax/referencing)=
 
 ## Markdown Links and Referencing
@@ -529,24 +521,21 @@ markdown: `[](syntax.md)` will result in: [](syntax.md).
 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/).
 
-````markdown
-```python
-from a import b
-c = "string"
-```
-````
 
+:::{myst-example}
 ```python
 from a import b
 c = "string"
 ```
+:::
 
 You can create and register your own lexer, using the [`pygments.lexers` entry point](https://pygments.org/docs/plugins/#register-plugins),
 or within a sphinx extension, with the [`app.add_lexer` method](inv:sphinx#*.Sphinx.add_lexer).
 
 Using the `myst_number_code_blocks` configuration option, you can also control whether code blocks are numbered by line.
 For example, using `myst_number_code_blocks = ["typescript"]`:
 
+:::{myst-example}
 ```typescript
 type MyBool = true | false;
 
@@ -555,58 +544,45 @@ interface User {
   id: number;
 }
 ```
+:::
 
 ### Show backticks inside raw markdown blocks
 
 If you'd like to show backticks inside of your markdown, 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:
 
-``` `` `hi` `` ```  will be rendered as: `` `hi` ``
-
-and
-
-`````
-````
-```
-hi
-```
-````
-`````
-
-will be rendered as:
+:::{myst-example}
+`` `hi` ``
 
 ````
 ```
 hi
 ```
 ````
+:::
 
 ## Tables
 
 Tables can be written using the standard [Github Flavoured Markdown syntax](https://github.github.com/gfm/#tables-extension-):
 
+:::{myst-example}
 ```md
 | foo | bar |
 | --- | --- |
 | baz | bim |
 ```
-
-| foo | bar |
-| --- | --- |
-| baz | bim |
+:::
 
 Cells in a column can be aligned using the `:` character:
 
+:::{myst-example}
 ```md
 | left | center | right |
 | :--- | :----: | ----: |
 | a    | b      | c     |
 ```
-
-| left | center | right |
-| :--- | :----: | ----: |
-| a    | b      | c     |
+:::
 
 :::{note}
 
@@ -632,11 +608,9 @@ MyST provides a few different syntaxes for including images in your documentatio
 
 The standard Markdown syntax is:
 
-```md
-![fishy](img/fun-fish.png)
-```
-
+:::{myst-example}
 ![fishy](img/fun-fish.png)
+:::
 
 But you can also enable extended image syntaxes, to control attributes like width and captions.
 See the [extended image syntax guide](syntax/images).
@@ -653,24 +627,18 @@ Their labels **start with `^`** and can then be any alphanumeric string (no spac
 All footnote definitions are collected, and displayed at the bottom of the page (in the order they are referenced).
 Note that un-referenced footnote definitions will not be displayed.
 
-```md
-- This is a manually-numbered footnote reference.[^3]
-- This is an auto-numbered footnote reference.[^myref]
-
-[^myref]: This is an auto-numbered footnote definition.
-[^3]: This is a manually-numbered footnote definition.
-```
-
+:::{myst-example}
 - This is a manually-numbered footnote reference.[^3]
 - This is an auto-numbered footnote reference.[^myref]
 
 [^myref]: This is an auto-numbered footnote definition.
 [^3]: This is a manually-numbered footnote definition.
+:::
 
 Any preceding text after a footnote definitions, which is
 indented by four or more spaces, will also be included in the footnote definition, and the text is rendered as MyST Markdown, e.g.
 
-```md
+:::{myst-example}
 A longer footnote definition.[^mylongdef]
 
 [^mylongdef]: This is the _**footnote definition**_.
@@ -683,37 +651,14 @@ A longer footnote definition.[^mylongdef]
 that are not separated by a blank line
 
 This is not part of the footnote.
-```
-
-A longer footnote definition.[^mylongdef]
-
-[^mylongdef]: This is the _**footnote definition**_.
-
-    That continues for all indented lines
-
-    - even other block elements
-
-    Plus any subsequent unindented lines,
-that are not separated by a blank line
-
-This is not part of the footnote.
+:::
 
 ````{important}
 Although footnote references can be used just fine within directives, e.g.[^myref],
 it is recommended that footnote definitions are not set within directives,
 unless they will only be referenced within that same directive:
 
-```md
-[^other]
-
-[^other]: A definition within a directive
-```
-
-[^other]
-
-[^other]: A definition within a directive
-
-This is because, in the current implementation, they may not be available to reference in text above that particular directive.
+This is because, they may not be available to reference in text outside that particular directive.
 ````
 
 By default, a transition line (with a `footnotes` class) will be placed before any footnotes.

myst_parser/_docs.py

@@ -224,3 +224,35 @@ def run(self):
         node = nodes.Element()
         self.state.nested_parse(text, 0, node)
         return node.children
+
+
+class MystExampleDirective(SphinxDirective):
+    """Directive to print an example."""
+
+    has_content = True
+    option_spec = {
+        "html": directives.flag,
+    }
+
+    def run(self):
+        """Run the directive."""
+        content_str = "\n".join(self.content)
+        backticks = "```"
+        while backticks in content_str:
+            backticks += "`"
+        content = f"""
+{backticks}``{{div}} myst-example
+
+{backticks}`{{div}} myst-example-source
+{backticks}markdown
+{content_str}
+{backticks}
+{backticks}`
+{backticks}`{{div}} myst-example-render
+{content_str}
+{backticks}`
+{backticks}``
+"""
+        node_ = nodes.Element()
+        self.state.nested_parse(content.splitlines(), self.content_offset, node_)
+        return node_.children

pyproject.toml

@@ -57,6 +57,7 @@ rtd = [
     # currently required to get sphinx v5
     "sphinx-book-theme==0.4.0rc1",
     "sphinx-design",
+    "sphinx-copybutton",
     "sphinxext-rediraffe~=0.2.7",
     "sphinxcontrib.mermaid~=0.7.1",
     "sphinxext-opengraph~=0.7.5",