📚 DOCS: Fix build

docs/_static/custom.css

@@ -0,0 +1,5 @@
+.code-cell > .highlight > pre {
+    border-left-color: green;
+    border-left-width: medium;
+    border-left-style: solid;
+}

docs/architecture.md

@@ -2,6 +2,7 @@
 
 # markdown-it design principles
 
+(md/data-flow)=
 ## Data flow
 
 Input data is parsed via nested chains of rules. There are 3 nested chains -
@@ -157,10 +158,9 @@ renderer override, but can be more simple.
 You also can write your own renderer to generate other formats than HTML, such as
 JSON/XML... You can even use it to generate AST.
 
-
 ## Summary
 
-This was mentioned in [Data flow](#data-flow), but let's repeat sequence again:
+This was mentioned in [Data flow](md/data-flow), but let's repeat sequence again:
 
 1. Blocks are parsed, and top level of token stream filled with block tokens.
 2. Content on inline containers is parsed, filling `.children` properties.

docs/conf.py

@@ -33,25 +33,25 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
-    "myst_nb",
+    "myst_parser",
     "sphinx_copybutton",
-    "sphinx_panels",
+    "sphinx_design",
 ]
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+nitpicky = True
 nitpick_ignore = [
     ("py:class", "Match"),
+    ("py:class", "Path"),
     ("py:class", "x in the interval [0, 1)."),
     ("py:class", "markdown_it.helpers.parse_link_destination._Result"),
     ("py:class", "markdown_it.helpers.parse_link_title._Result"),
     ("py:class", "MarkdownIt"),
+    ("py:class", "RuleFunc"),
     ("py:class", "_NodeType"),
     ("py:class", "typing_extensions.Protocol"),
 ]
@@ -70,7 +70,8 @@
     "repository_branch": "master",
     "path_to_docs": "docs",
 }
-panels_add_boostrap_css = False
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -100,7 +101,7 @@ def run_apidoc(app):
     this_folder = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
     api_folder = os.path.join(this_folder, "api")
     module_path = os.path.normpath(os.path.join(this_folder, "../"))
-    ignore_paths = ["../setup.py", "../conftest.py", "../tests", "../benchmarking"]
+    ignore_paths = ["../profiler.py", "../conftest.py", "../tests", "../benchmarking"]
     ignore_paths = [
         os.path.normpath(os.path.join(this_folder, p)) for p in ignore_paths
     ]
@@ -120,6 +121,7 @@ def run_apidoc(app):
 
     argv = ["-M", "--separate", "-o", api_folder, module_path] + ignore_paths
 
+    apidoc.OPTIONS.append("ignore-module-all")
     apidoc.main(argv)
 
     # we don't use this
@@ -131,3 +133,17 @@ 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)

pyproject.toml

@@ -47,11 +47,11 @@ compare = [
 linkify = ["linkify-it-py~=1.0"]
 plugins = ["mdit-py-plugins"]
 rtd = [
-    "myst-nb==0.13.0a1",
+    "myst-parser",
     "pyyaml",
-    "sphinx>=2,<4",
+    "sphinx",
     "sphinx-copybutton",
-    "sphinx-panels~=0.4.0",
+    "sphinx-design",
     "sphinx_book_theme",
 ]
 testing = [

tox.ini

@@ -37,12 +37,15 @@ commands = pytest benchmarking/bench_packages.py {posargs}
 
 [testenv:docs-{update,clean}]
 extras = linkify,plugins,rtd
-whitelist_externals = rm
+whitelist_externals =
+    echo
+    rm
 setenv =
     update: SKIP_APIDOC = true
 commands =
     clean: rm -rf docs/_build
     sphinx-build -nW --keep-going -b {posargs:html} docs/ docs/_build/{posargs:html}
+commands_post = echo "open file://{toxinidir}/docs/_build/{posargs:html}/index.html"
 
 [testenv:profile]
 description = run profiler (use e.g. `firefox .tox/prof/output.svg` to open)