Sphinx 7

.github/workflows/tests.yml

@@ -26,15 +26,15 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.8", "3.9", "3.10"]
-        sphinx: [">=5,<6"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        sphinx: ["~=5.0","~=6.0","~=7.0"]
         include:
           - os: windows-latest
             python-version: 3.9
-            sphinx: ">=5,<6"
+            sphinx: "~=5.0"
           - os: macos-latest
             python-version: 3.9
-            sphinx: ">=5,<6"
+            sphinx: "~=5.0"
 
     runs-on: ${{ matrix.os }}
 
@@ -44,10 +44,29 @@ jobs:
       uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
+        cache: pip
+    - name: Install myst-nb with Sphinx ${{ matrix.sphinx }}
+      run: |
+        pip install --upgrade pip
+        pip install --upgrade "Sphinx${{ matrix.sphinx }}" -e .[testing]
+
+    - name: Run pytest
+      run: pytest --durations=10
+
+  coverage:
+    needs: [tests]
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+        cache: pip
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip
-        pip install "sphinx${{ matrix.sphinx }}"
+        pip install --upgrade pip
         pip install -e .[testing]
 
     - name: Run pytest
@@ -59,13 +78,11 @@ jobs:
       # this is why we run `coverage xml` afterwards (required by codecov)
 
     - name: Upload to Codecov
-      if: github.repository == 'executablebooks/MyST-NB' && matrix.python-version == '3.9' && matrix.os == 'ubuntu-latest'
       uses: codecov/codecov-action@v3
       with:
         name: myst-nb-pytests
         flags: pytests
         files: ./coverage.xml
-        fail_ci_if_error: true
 
   publish:
 

.pre-commit-config.yaml

@@ -20,7 +20,7 @@ repos:
     - id: trailing-whitespace
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.2
+    rev: v3.7.0
     hooks:
     - id: pyupgrade
       args: [--py37-plus]
@@ -42,13 +42,13 @@ repos:
       additional_dependencies: [flake8-bugbear]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.2.0
+    rev: v1.4.1
     hooks:
     - id: mypy
       args: [--config-file=pyproject.toml]
       additional_dependencies:
       - importlib_metadata
-      - myst-parser~=0.18.0
+      - myst-parser~=1.0.0
       - "sphinx~=5.0"
       - nbclient
       - types-PyYAML

CHANGELOG.md

@@ -92,7 +92,7 @@ WARNING: 'jupyter_execute_notebooks' is deprecated for 'nb_execution_mode' [myst
 
 `nb_render_priority` has been removed and replaced by `nb_mime_priority_overrides`, which has a different format and is more flexible. See [Outputs MIME priority](docs/render/format_code_cells.md) for more information.
 
-As per the changes in [`myst_parser`](myst:develop/_changelog), the `dollarmath` syntax extension is no longer included by default.
+As per the changes in [`myst_parser`](inv:myst#develop/_changelog), the `dollarmath` syntax extension is no longer included by default.
 To re-add this extension, ensure that it is specified in your `conf.py`: `myst_enable_extensions = ["dollarmath"]`.
 
 For cell-level configuration the top-level key `render` has now been deprecated for `mystnb`.
@@ -168,7 +168,7 @@ See [Embedding outputs as variables](docs/render/glue.md) for more details.
   - `nbconvert`
 - Updated:
   - `Python`: `3.6+ -> 3.7+`
-  - `myst_parser`: [`0.15 -> 0.17`](myst:develop/_changelog)
+  - `myst_parser`: [`0.15 -> 0.17`](inv:myst#develop/_changelog)
   - `jupyter-cache`: [`0.4 -> 0.5`](https://github.com/executablebooks/jupyter-cache/blob/master/CHANGELOG.md)
   - `sphinx-togglebutton`: [`0.1 -> 0.3`](https://sphinx-togglebutton.readthedocs.io/en/latest/changelog.html)
 

docs/authoring/custom-formats.Rmd

@@ -21,7 +21,7 @@ nb_custom_formats = {
 ```
 
 - The string should be a Python function that will be loaded by `import mylibrary.converter_function`
-- The function should take a file's contents (as a `str`) and return an [nbformat.NotebookNode](nbformat:api)
+- The function should take a file's contents (as a `str`) and return an [nbformat.NotebookNode](inv:nbformat#api)
 
 If the function takes additional keyword arguments, then you can specify these as dictionary in a second argument.
 For example this is what the default conversion would look like:

docs/authoring/jupyter-notebooks.md

@@ -16,13 +16,13 @@ Sphinx using the MyST parser.[^download]
 
 :::{seealso}
 For more information about what you can write with MyST Markdown, see the
-[MyST Parser documentation](myst:intro/get-started).
+[MyST Parser documentation](inv:myst#intro/get-started).
 :::
 
 ### Configuration
 
-The MyST-NB parser derives from [the base MyST-Parser](myst:intro/get-started), and so all the same configuration options are available.
-See the [MyST configuration options](myst:sphinx/config-options) for the full set of options, and [MyST syntax guide](myst:syntax/core) for all the syntax options.
+The MyST-NB parser derives from [the base MyST-Parser](inv:myst#intro/get-started), and so all the same configuration options are available.
+See the [MyST configuration options](inv:myst#sphinx/config-options) for the full set of options, and [MyST syntax guide](inv:myst#syntax/core) for all the syntax options.
 
 To build documentation from this notebook, the following options are set:
 
@@ -38,7 +38,7 @@ myst_url_schemes = ("http", "https", "mailto")
 ```
 
 :::{note}
-Loading the `myst_nb` extension also activates the [`myst_parser`](myst:index) extension, for enabling the MyST flavour of Markdown.
+Loading the `myst_nb` extension also activates the [`myst_parser`](inv:myst#index) extension, for enabling the MyST flavour of Markdown.
 It is not required to add this explicitly in the list of `extensions`.
 :::
 
@@ -53,7 +53,7 @@ For example, here's the MyST-NB logo:
 
 ![myst-nb logo](../_static/logo-wide.svg)
 
-By adding `"html_image"` to the `myst_enable_extensions` list in the sphinx configuration ([see here](myst:syntax/images)), you can even add HTML `img` tags with attributes:
+By adding `"html_image"` to the `myst_enable_extensions` list in the sphinx configuration ([see here](inv:myst#syntax/images)), you can even add HTML `img` tags with attributes:
 
 ```html
 <img src="../_static/logo-wide.svg" alt="logo" width="200px" class="shadow mb-2">
@@ -66,7 +66,7 @@ For example, here's a note admonition block:
 
 :::::{note}
 **Wow**, a note!
-It was generated with this code ([as explained here](myst:syntax/admonitions)):
+It was generated with this code ([as explained here](inv:myst:std:label#syntax/admonitions)):
 
 ````md
 :::{note}
@@ -77,7 +77,7 @@ It was generated with this code ([as explained here](myst:syntax/admonitions)):
 :::::
 
 If you wish to use "bare" LaTeX equations, then you should add `"amsmath"` to the `myst_enable_extensions` list in the sphinx configuration.
-This is [explained here](myst:syntax/amsmath), and works as such:
+This is [explained here](inv:myst:std:label#syntax/amsmath), and works as such:
 
 ```latex
 \begin{equation}
@@ -110,7 +110,7 @@ $$e^{i\pi} + 1 = 0$$ (euler)
 Euler's identity, equation {math:numref}`euler`, was elected one of the
 most beautiful mathematical formulas.
 
-You can see the syntax used for this example [here in the MyST documentation](myst:syntax/math).
+You can see the syntax used for this example [here in the MyST documentation](inv:myst:std:label#syntax/math).
 
 ## Code cells and outputs
 

docs/index.md

@@ -86,7 +86,7 @@ Build single or collections of documents into multiple formats (HTML, PDF, ...).
 
 MyST-NB is a module within the [Executable Books Project](https://executablebooks.org),
 an international collaboration to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem.
-It is also a core component of [Jupyter Book](jb:intro).
+It is also a core component of [Jupyter Book](inv:jb#intro).
 
 Check out the [Gallery of Jupyter Books](https://executablebooks.org/en/latest/gallery),
 for inspiration from across the community.

docs/requirements.txt

@@ -1,2 +1,2 @@
 # this is only required by coconut kernel
-ipython<=7.11.0
+ipython<=8.14.0

myst_nb/__init__.py

@@ -1,5 +1,5 @@
 """A docutils/sphinx parser for Jupyter Notebooks."""
-__version__ = "0.17.2"
+__version__ = "0.18.0"
 
 
 def setup(app):

myst_nb/core/config.py

@@ -1,6 +1,7 @@
 """Configuration for myst-nb."""
 import dataclasses as dc
 from enum import Enum
+import sys
 from typing import Any, Callable, Dict, Iterable, Optional, Sequence, Tuple
 
 from myst_parser.config.dc_validators import (
@@ -12,7 +13,13 @@
     optional,
     validate_fields,
 )
-from typing_extensions import Literal
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal  # noqa: F401
+
+from myst_nb.warnings_ import MystNBWarnings
 
 
 def custom_formats_converter(value: dict) -> Dict[str, Tuple[str, dict, bool]]:
@@ -130,7 +137,7 @@ def __post_init__(self):
         default_factory=dict,
         metadata={
             "help": "Custom formats for reading notebook; suffix -> reader",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "sections": (Section.global_lvl, Section.read),
         },
     )
@@ -184,10 +191,18 @@ def __post_init__(self):
             "validator": deep_mapping(instance_of(str), instance_of(str)),
             "help": "Mapping of kernel name regex to replacement kernel name"
             "(applied before execution)",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "sections": (Section.global_lvl, Section.execute),
         },
     )
+    eval_name_regex: str = dc.field(
+        default=r"^[a-zA-Z_][a-zA-Z0-9_]*$",
+        metadata={
+            "validator": instance_of(str),
+            "help": "Regex that matches permitted values of eval expressions",
+            "sections": (Section.global_lvl, Section.file_lvl, Section.execute),
+        },
+    )
     execution_mode: Literal["off", "force", "auto", "cache", "inline"] = dc.field(
         default="auto",
         metadata={
@@ -220,7 +235,7 @@ def __post_init__(self):
             "validator": deep_iterable(instance_of(str)),
             "help": "Exclude (POSIX) glob patterns for notebooks",
             "legacy_name": "execution_excludepatterns",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "sections": (Section.global_lvl, Section.execute),
         },
     )
@@ -387,7 +402,7 @@ def __post_init__(self):
             "help": "Overrides for the base render priority of mime types: "
             "list of (builder name, mime type, priority)",
             # TODO how to allow this in docutils?
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "sections": (Section.global_lvl, Section.file_lvl, Section.render),
         },
         repr=False,
@@ -454,7 +469,7 @@ def __post_init__(self):
         metadata={
             "validator": deep_mapping(instance_of(str), instance_of((str, int))),
             "help": "Options for image outputs (class|alt|height|width|scale|align)",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             # TODO backward-compatible change to "image_options"?
             "cell_key": "image",
             "sections": (
@@ -471,7 +486,7 @@ def __post_init__(self):
         metadata={
             "validator": deep_mapping(instance_of(str), instance_of((str, int))),
             "help": "Options for figure outputs (classes|name|caption|caption_before)",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "cell_key": "figure",
             "sections": (
                 Section.global_lvl,
@@ -505,7 +520,7 @@ def __post_init__(self):
                 instance_of(str), deep_mapping(instance_of(str), instance_of(str))
             ),
             "help": "Javascript to be loaded on pages containing ipywidgets",
-            "docutils_exclude": True,
+            "omit": ["docutils"],
             "sections": (Section.global_lvl, Section.render),
         },
         repr=False,
@@ -567,7 +582,7 @@ def get_cell_level_config(
         self,
         field_name: str,
         cell_metadata: Dict[str, Any],
-        warning_callback: Callable[[str, str], Any],
+        warning_callback: Callable[[str, MystNBWarnings], Any],
     ) -> Any:
         """Get a configuration value at the cell level.
 
@@ -593,7 +608,7 @@ def get_cell_level_config(
             warning_callback(
                 f"Deprecated `cell_metadata_key` 'render' "
                 f"found, replace with {self.cell_metadata_key!r}",
-                "cell_metadata_key",
+                MystNBWarnings.CELL_METADATA_KEY,
             )
             cell_meta = cell_metadata["render"]
         else:
@@ -611,7 +626,10 @@ def get_cell_level_config(
                             field.metadata["validator"](self, field, value)
                     return value
             except Exception as exc:
-                warning_callback(f"Cell metadata invalid: {exc}", "cell_config")
+                warning_callback(
+                    f"Cell metadata invalid: {exc}",
+                    MystNBWarnings.CELL_CONFIG,
+                )
 
         # default/global/file level should have already been merged
         return getattr(self, field.name)

myst_nb/core/execute/base.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 from pathlib import Path
-import re
 from typing import Any
 
 from nbformat import NotebookNode
@@ -39,9 +38,6 @@ class EvalNameError(Exception):
     """An exception for if an evaluation variable name is invalid."""
 
 
-EVAL_NAME_REGEX = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
-
-
 class NotebookClientBase:
     """A base client for interacting with Jupyter notebooks.
 

myst_nb/core/execute/inline.py

@@ -3,6 +3,7 @@
 
 import asyncio
 from datetime import datetime
+import re
 import shutil
 from tempfile import mkdtemp
 import time
@@ -22,7 +23,7 @@
 
 from myst_nb.ext.glue import extract_glue_data_cell
 
-from .base import EVAL_NAME_REGEX, EvalNameError, ExecutionError, NotebookClientBase
+from .base import EvalNameError, ExecutionError, NotebookClientBase
 
 
 class NotebookClientInline(NotebookClientBase):
@@ -148,7 +149,7 @@ def code_cell_outputs(
         return cell.get("execution_count", None), cell.get("outputs", [])
 
     def eval_variable(self, name: str) -> list[NotebookNode]:
-        if not EVAL_NAME_REGEX.match(name):
+        if not re.match(self.nb_config.eval_name_regex, name):
             raise EvalNameError(name)
         return self._client.eval_expression(name)