📚 DOCS: Full update

Author: chrisjsewell

CHANGELOG.md

@@ -16,7 +16,7 @@ Full Changelog: [v0.17.2...v0.18.0](https://github.com/executablebooks/MyST-Pars
 
 This release adds support for Sphinx v5 (dropping v3), restructures the code base into modules, and also restructures the documentation, to make it easier for developers/users to follow.
 
-It also introduces **document-level configuration**  *via* the Markdown top-matter, under the `myst` key.
+It also introduces **document-level configuration**  *via* the Markdown front-matter, under the `myst` key.
 See the [Local configuration](docs/configuration.md) section for more information.
 
 ### Breaking changes
@@ -28,7 +28,7 @@ The `to_docutils`, `to_html`, `to_tokens` (from `myst_parser/main.py`) and `mock
 Instead, for single page builds, users should use the docutils parser API/CLI (see [](docs/docutils.md)),
 and for testing, functionality has been moved to <https://github.com/chrisjsewell/sphinx-pytest>.
 
-The top-level `html_meta` and `substitutions` top-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the `myst` config, e.g.
+The top-level `html_meta` and `substitutions` front-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the `myst` config, e.g.
 
 ```yaml
 ---
@@ -100,7 +100,7 @@ In addition, configuration to more finely tune this behaviour has been added.
 - `myst_url_schemes=("http", "https")`, sets what URL schemes are treated as (1)
 - `myst_ref_domains=("std", "py")`, sets what Sphinx reference domains are checked, when handling (3)
 
-See [Markdown Links and Referencing](docs/syntax/syntax.md#markdown-links-and-referencing) for more information.
+See [Markdown Links and Referencing](docs/syntax/cross-referencing.md) for more information.
 
 ### ‼️ Dollarmath is now disabled by default
 
@@ -143,7 +143,7 @@ would be equivalent to:
 # My Title with *emphasis*
 ```
 
-See [Front matter](docs/syntax/syntax.md#front-matter) for more information.
+See [Front matter](docs/configuration.md) for more information.
 
 ### 👌 Internal improvements
 
@@ -291,7 +291,7 @@ is converted to:
 
 These classes should be supported by most sphinx HTML themes.
 
-See [Tables syntax](docs/syntax/syntax.md#tables) for more information.
+See [Tables syntax](docs/syntax/tables.md) for more information.
 
 ### Pull Requests
 
@@ -382,7 +382,7 @@ In particular for users, this update alters the parsing of tables to be consiste
   > {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
   ```
 
-  See [the roles syntax guide](docs/syntax/syntax.md) for further information.
+  See [the roles syntax guide](docs/syntax/roles-and-directives.md) for further information.
 
 - The **`dmath_double_inline`** configuration option allows display math (i.e. `$$`) within an inline context.
   See [the math syntax guide](docs/syntax/optional.md#math-shortcuts) for further information.
@@ -467,7 +467,7 @@ Minor fixes:
 : If the label is an integer, then it will always use this integer for the rendered label (i.e. they are manually numbered).
 : Add `myst_footnote_transition` configuration, to turn on/off transition line.
 : Add `footnotes` class to transition `<hr>` in HTML.
-: See [the syntax guide](docs/syntax/syntax.md) for further information.
+: See [the typography guide](docs/syntax/typography.md) for further information.
 
 👌 IMPROVE: `substitution` extension logic
 

docs/_static/local.css

@@ -1,25 +1,13 @@
+/** landing page logo **/
+#landing-page-logo {
+    background: none;
+}
+
 /** Add a counter before subsections **/
-h1 {
+h1:not(.rubric) {
     counter-reset: subsection;
     text-decoration: underline;
 }
-h2 {
-    counter-reset: subsubsection;
-}
-h2::before {
-    counter-increment: subsection;
-    content: counter(subsection) ". ";
-}
-.tippy-box h2::before {
-    content: unset;
-}
-h3::before {
-    counter-increment: subsubsection;
-    content: counter(subsection) "." counter(subsubsection) ". ";
-}
-.tippy-box h3::before {
-    content: unset;
-}
 
 /** MyST examples */
 .myst-example {
@@ -35,6 +23,9 @@ h3::before {
 .myst-example-render {
     padding: 0.5rem;
 }
+.myst-example-render > :first-child {
+    margin-top: 0.5rem;
+}
 
 /** No icon for admonitions with no-icon class */
 div.admonition.no-icon > .admonition-title::before {
@@ -45,24 +36,30 @@ div.admonition.no-icon > .admonition-title {
 }
 
 /* Live preview page */
-iframe.pyscript, textarea.pyscript {
-    width: 100%;
-    height: 100%;
-    min-height: 300px;
-}
-div.pyscript {
-    min-height: 300px;
-}
-iframe.pyscript {
-    padding: 4px;
+@media (min-width: 768px) {
+    .preview-input-tabs {
+        height: 100%;
+    }
+    textarea.pyscript.input {
+        height: 100%;
+    }
 }
 textarea.pyscript {
+    width: 100%;
+    min-height: 300px;
     padding: 30px 20px 20px;
     border-radius: 8px;
     resize: vertical;
     font-size: 16px;
     font-family: monospace;
 }
+textarea.pyscript.output {
+    height: 100%;
+}
+div.pyscript {
+    min-height: 300px;
+}
+
 .display-flex {
     display: flex;
 }

docs/conf.py

@@ -4,10 +4,11 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import hashlib
 from datetime import date
+from pathlib import Path
 
 from sphinx.application import Sphinx
-from sphinx.transforms.post_transforms import SphinxPostTransform
 
 from myst_parser import __version__
 
@@ -32,6 +33,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx_design",
     "sphinx_copybutton",
     "sphinxext.rediraffe",
@@ -40,6 +42,7 @@
     "sphinxext.opengraph",
     "sphinx_pyscript",
     "sphinx_tippy",
+    "sphinx_togglebutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -61,6 +64,7 @@
 # -- Autodoc settings ---------------------------------------------------
 
 autodoc2_packages = ["../myst_parser"]
+autodoc2_exclude_files = ["_docs.py"]
 autodoc2_hidden_objects = ["dunder", "private", "inherited"]
 autodoc2_replace_annotations = [
     ("re.Pattern", "typing.Pattern"),
@@ -71,9 +75,14 @@
     ("myst_parser._compat.TypedDict", "typing.TypedDict"),
     ("sphinx.directives.SphinxDirective", "sphinx.util.docutils.SphinxDirective"),
 ]
+autodoc2_docstring_parser_regexes = [
+    ("myst_parser", "myst"),
+    (r"myst_parser\.setup", "myst"),
+]
 nitpicky = True
 nitpick_ignore_regex = [
     (r"py:.*", r"docutils\..*"),
+    (r"py:.*", r"pygments\..*"),
 ]
 nitpick_ignore = [
     ("py:obj", "myst_parser._docs._ConfigBase"),
@@ -101,7 +110,6 @@
     "tasklist",
     "attrs_inline",
     "attrs_block",
-    "inv_link",
 ]
 myst_url_schemes = {
     "http": None,
@@ -131,6 +139,10 @@
 myst_footnote_transition = True
 myst_dmath_double_inline = True
 myst_enable_checkboxes = True
+myst_substitutions = {
+    "role": "[role](#syntax/roles)",
+    "directive": "[directive](#syntax/directives)",
+}
 
 # -- HTML output -------------------------------------------------
 
@@ -146,6 +158,7 @@
     "path_to_docs": "docs",
     "use_repository_button": True,
     "use_edit_page_button": True,
+    "use_issues_button": True,
 }
 # OpenGraph metadata
 ogp_site_url = "https://myst-parser.readthedocs.io/en/latest"
@@ -163,6 +176,7 @@
 
 rediraffe_redirects = {
     "using/intro.md": "sphinx/intro.md",
+    "syntax/syntax.md": "syntax/typography.md",
     "sphinx/intro.md": "intro.md",
     "using/use_api.md": "api/index.md",
     "api/index.md": "api/reference.rst",
@@ -191,46 +205,40 @@
 # -- Local Sphinx extensions -------------------------------------------------
 
 
-class StripUnsupportedLatex(SphinxPostTransform):
-    """Remove unsupported nodes from the doctree."""
-
-    default_priority = 900
-
-    def run(self):
-        if self.app.builder.format != "latex":
-            return
-        from docutils import nodes
-
-        for node in self.document.findall():
-            if node.tagname == "image" and node["uri"].endswith(".svg"):
-                node.parent.replace(node, nodes.inline("", "Removed SVG image"))
-            if node.tagname == "mermaid":
-                node.parent.replace(node, nodes.inline("", "Removed Mermaid diagram"))
-
-
 def setup(app: Sphinx):
     """Add functions to the Sphinx setup."""
     from myst_parser._docs import (
         DirectiveDoc,
         DocutilsCliHelpDirective,
+        MystAdmonitionDirective,
         MystConfigDirective,
         MystExampleDirective,
+        MystLexer,
+        MystToHTMLDirective,
         MystWarningsDirective,
+        NumberSections,
+        StripUnsupportedLatex,
     )
 
     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_directive("myst-admonitions", MystAdmonitionDirective)
+    app.add_directive("myst-to-html", MystToHTMLDirective)
     app.add_post_transform(StripUnsupportedLatex)
+    app.add_post_transform(NumberSections)
     app.connect("html-page-context", add_version_to_css)
+    app.add_lexer("myst", MystLexer)
 
 
-def add_version_to_css(app, pagename, templatename, context, doctree):
+def add_version_to_css(app: Sphinx, pagename, templatename, context, doctree):
     """Add the version number to the local.css file, to bust the cache for changes."""
     if app.builder.name != "html":
         return
     if "_static/local.css" in context.get("css_files", {}):
+        css = Path(app.srcdir, "_static/local.css").read_text("utf8")
+        hashed = hashlib.sha256(css.encode("utf-8")).hexdigest()
         index = context["css_files"].index("_static/local.css")
-        context["css_files"][index] = f"_static/local.css?v={__version__}"
+        context["css_files"][index] = f"_static/local.css?hash={hashed}"