📚 DOCS: re-activate code cells (#269)

Author: chrisjsewell

docs/_static/custom.css

@@ -1,4 +1,4 @@
-.code-cell > .highlight > pre {
+.cell_output > .output > .highlight > pre {
     border-left-color: green;
     border-left-width: medium;
     border-left-style: solid;

docs/conf.py

@@ -36,6 +36,7 @@
     "myst_parser",
     "sphinx_copybutton",
     "sphinx_design",
+    "jupyter_sphinx",
 ]
 
 # List of patterns, relative to source directory, that match files and
@@ -135,17 +136,3 @@ def setup(app):
     """Add functions to the Sphinx setup."""
     if os.environ.get("SKIP_APIDOC", None) is None:
         app.connect("builder-inited", run_apidoc)
-
-    from sphinx.directives.code import CodeBlock
-
-    class CodeCell(CodeBlock):
-        """Custom code block directive."""
-
-        def run(self):
-            """Run the directive."""
-            self.options["class"] = ["code-cell"]
-            return super().run()
-
-    # note, these could be run by myst-nb,
-    # but currently this causes a circular dependency issue
-    app.add_directive("code-cell", CodeCell)

docs/using.md

@@ -27,17 +27,17 @@ then these are converted to other formats using 'renderers'.
 
 The simplest way to understand how text will be parsed is using:
 
-```{code-cell} python
+```{jupyter-execute}
 from pprint import pprint
 from markdown_it import MarkdownIt
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt()
 md.render("some *text*")
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 for token in md.parse("some *text*"):
     print(token)
     print()
@@ -59,48 +59,48 @@ You can define this configuration *via* directly supplying a dictionary or a pre
   Compared to `commonmark`, it enables the table, strikethrough and linkify components.
   **Important**, to use this configuration you must have `linkify-it-py` installed.
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it.presets import zero
 zero.make()
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("zero")
 md.options
 ```
 
 You can also override specific options:
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("zero", {"maxNesting": 99})
 md.options
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 pprint(md.get_active_rules())
 ```
 
 You can find all the parsing rules in the source code:
 `parser_core.py`, `parser_block.py`,
 `parser_inline.py`.
 
-```{code-cell} python
+```{jupyter-execute}
 pprint(md.get_all_rules())
 ```
 
 Any of the parsing rules can be enabled/disabled, and these methods are "chainable":
 
-```{code-cell} python
+```{jupyter-execute}
 md.render("- __*emphasise this*__")
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 md.enable(["list", "emphasis"]).render("- __*emphasise this*__")
 ```
 
 You can temporarily modify rules with the `reset_rules` context manager.
 
-```{code-cell} python
+```{jupyter-execute}
 with md.reset_rules():
     md.disable("emphasis")
     print(md.render("__*emphasise this*__"))
@@ -109,7 +109,7 @@ md.render("__*emphasise this*__")
 
 Additionally `renderInline` runs the parser with all block syntax rules disabled.
 
-```{code-cell} python
+```{jupyter-execute}
 md.renderInline("__*emphasise this*__")
 ```
 
@@ -140,7 +140,7 @@ The `smartquotes` and `replacements` components are intended to improve typograp
 
 Both of these components require typography to be turned on, as well as the components enabled:
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("commonmark", {"typographer": True})
 md.enable(["replacements", "smartquotes"])
 md.render("'single quotes' (c)")
@@ -151,7 +151,7 @@ md.render("'single quotes' (c)")
 The `linkify` component requires that [linkify-it-py](https://github.com/tsutsu3/linkify-it-py) be installed (e.g. *via* `pip install markdown-it-py[linkify]`).
 This allows URI autolinks to be identified, without the need for enclosing in `<>` brackets:
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("commonmark", {"linkify": True})
 md.enable(["linkify"])
 md.render("github.com")
@@ -163,7 +163,7 @@ Plugins load collections of additional syntax rules and render methods into the
 A number of useful plugins are available in [`mdit_py_plugins`](https://github.com/executablebooks/mdit-py-plugins) (see [the plugin list](./plugins.md)),
 or you can create your own (following the [markdown-it design principles](./architecture.md)).
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it import MarkdownIt
 import mdit_py_plugins
 from mdit_py_plugins.front_matter import front_matter_plugin
@@ -175,7 +175,7 @@ md = (
     .use(footnote_plugin)
     .enable('table')
 )
-text = ("""
+text = ("""\
 ---
 a: 1
 ---
@@ -188,7 +188,7 @@ A footnote [^1]
 
 [^1]: some details
 """)
-md.render(text)
+print(md.render(text))
 ```
 
 ## The Token Stream
@@ -197,7 +197,7 @@ md.render(text)
 
 Before rendering, the text is parsed to a flat token stream of block level syntax elements, with nesting defined by opening (1) and closing (-1) attributes:
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("commonmark")
 tokens = md.parse("""
 Here's some *text*
@@ -211,37 +211,37 @@ Here's some *text*
 Naturally all openings should eventually be closed,
 such that:
 
-```{code-cell} python
+```{jupyter-execute}
 sum([t.nesting for t in tokens]) == 0
 ```
 
 All tokens are the same class, which can also be created outside the parser:
 
-```{code-cell} python
+```{jupyter-execute}
 tokens[0]
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it.token import Token
 token = Token("paragraph_open", "p", 1, block=True, map=[1, 2])
 token == tokens[0]
 ```
 
 The `'inline'` type token contain the inline tokens as children:
 
-```{code-cell} python
+```{jupyter-execute}
 tokens[1]
 ```
 
 You can serialize a token (and its children) to a JSONable dictionary using:
 
-```{code-cell} python
+```{jupyter-execute}
 print(tokens[1].as_dict())
 ```
 
 This dictionary can also be deserialized:
 
-```{code-cell} python
+```{jupyter-execute}
 Token.from_dict(tokens[1].as_dict())
 ```
 
@@ -254,7 +254,7 @@ Token.from_dict(tokens[1].as_dict())
 In some use cases it may be useful to convert the token stream into a syntax tree,
 with opening/closing tokens collapsed into a single token that contains children.
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it.tree import SyntaxTreeNode
 
 md = MarkdownIt("commonmark")
@@ -274,11 +274,11 @@ print(node.pretty(indent=2, show_text=True))
 
 You can then use methods to traverse the tree
 
-```{code-cell} python
+```{jupyter-execute}
 node.children
 ```
 
-```{code-cell} python
+```{jupyter-execute}
 print(node[0])
 node[0].next_sibling
 ```
@@ -302,7 +302,7 @@ def function(renderer, tokens, idx, options, env):
 
 You can inject render methods into the instantiated render class.
 
-```{code-cell} python
+```{jupyter-execute}
 md = MarkdownIt("commonmark")
 
 def render_em_open(self, tokens, idx, options, env):
@@ -319,7 +319,7 @@ Also `add_render_rule` method is specific to Python, rather than adding directly
 
 You can also subclass a render and add the method there:
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it.renderer import RendererHTML
 
 class MyRenderer(RendererHTML):
@@ -332,7 +332,7 @@ md.render("*a*")
 
 Plugins can support multiple render types, using the `__output__` attribute (this is currently a Python only feature).
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it.renderer import RendererHTML
 
 class MyRenderer1(RendererHTML):
@@ -358,7 +358,7 @@ print(md.render("*a*"))
 
 Here's a more concrete example; let's replace images with vimeo links to player's iframe:
 
-```{code-cell} python
+```{jupyter-execute}
 import re
 from markdown_it import MarkdownIt
 
@@ -384,7 +384,7 @@ print(md.render("![](https://www.vimeo.com/123)"))
 
 Here is another example, how to add `target="_blank"` to all links:
 
-```{code-cell} python
+```{jupyter-execute}
 from markdown_it import MarkdownIt
 
 def render_blank_link(self, tokens, idx, options, env):
@@ -402,7 +402,7 @@ print(md.render("[a]\n\n[a]: b"))
 
 You can also render a token stream directly to markdown via the `MDRenderer` class from [`mdformat`](https://github.com/executablebooks/mdformat):
 
-```{code-cell} python
+```python
 from markdown_it import MarkdownIt
 from mdformat.renderer import MDRenderer
 

pyproject.toml

@@ -52,6 +52,7 @@ rtd = [
     "sphinx-copybutton",
     "sphinx-design",
     "sphinx_book_theme",
+    "jupyter_sphinx",
 ]
 testing = [
     "coverage",