JUST FOR TESTING: Sphinx 8.2.0rc1

.circleci/config.yml

@@ -45,7 +45,7 @@ jobs:
           name: Installing Sphinx
           # See https://github.com/sphinx-doc/sphinx/issues/12331
           command: |
-            $PIP_INSTALL "sphinx !=7.3.0, != 7.3.1, != 7.3.2, != 7.3.3, != 7.3.4, != 7.3.5, != 7.3.6, != 7.3.7"
+            $PIP_INSTALL "sphinx == 8.2.0rc1"
 
       - run:
           name: Installing nbsphinx

.github/workflows/version-matrix.yml

@@ -18,6 +18,10 @@ jobs:
           # default Python, latest Sphinx
           - env: {}
 
+          # latest Sphinx release candidate
+          - env:
+              SPHINX_PACKAGE: "sphinx==8.2.0rc1"
+
           # a few older Sphinx releases using default Python version
           - env:
               SPHINX_PACKAGE: "sphinx==5.0.0 sphinxcontrib-bibtex==2.5.0"

.readthedocs.yml

@@ -17,4 +17,6 @@ python:
     - method: pip
       path: .
     - requirements: doc/fallback_theme.txt
+sphinx:
+  configuration: doc/conf.py
 formats: all

doc/a-markdown-file-block.md

@@ -0,0 +1,56 @@
+# Using Markdown Files
+
+Sphinx on its own doesn't know how to handle Markdown files,
+but there are extensions that enable their usage as Sphinx source files.
+For an example, see the
+[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html).
+
+Alternatively, when using `nbsphinx` it is also possible to use Markdown
+files via [custom notebook formats](custom-formats.pct.py).
+
+You only need to install the [jupytext](https://jupytext.readthedocs.io/)
+package and add a configuration setting to `conf.py`,
+which can be used to select one of
+[several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats-markdown.html)
+(here we are using R Markdown):
+
+```python
+nbsphinx_custom_formats = {
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
+}
+```
+
+This very page was generated from a Markdown file using these settings.
+
+
+## Links to Notebooks (and Other Sphinx Source Files)
+
+Links to other Sphinx source files can be created like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks).
+
+
+## Math
+
+Mathematical equations can be used just like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Equations).
+
+Or as a separate block:
+
+\begin{equation*}
+\int\limits_{-\infty}^\infty f(x) \delta(x - x_0) dx = f(x_0)
+\end{equation*}
+
+
+## Tables
+
+A     | B     | A and B
+------|-------|--------
+False | False | False
+True  | False | False
+False | True  | False
+True  | True  | True
+
+
+## Images
+
+![Jupyter notebook icon](images/notebook_icon.png)

doc/a-markdown-file-inline.md

@@ -0,0 +1,52 @@
+# Using Markdown Files
+
+Sphinx on its own doesn't know how to handle Markdown files,
+but there are extensions that enable their usage as Sphinx source files.
+For an example, see the
+[Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/markdown.html).
+
+Alternatively, when using `nbsphinx` it is also possible to use Markdown
+files via [custom notebook formats](custom-formats.pct.py).
+
+You only need to install the [jupytext](https://jupytext.readthedocs.io/)
+package and add a configuration setting to `conf.py`,
+which can be used to select one of
+[several Markdown flavors supported by jupytext](https://jupytext.readthedocs.io/en/latest/formats-markdown.html)
+(here we are using R Markdown):
+
+```python
+nbsphinx_custom_formats = {
+    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
+}
+```
+
+This very page was generated from a Markdown file using these settings.
+
+
+## Links to Notebooks (and Other Sphinx Source Files)
+
+Links to other Sphinx source files can be created like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Links-to-Other-Notebooks).
+
+
+## Math
+
+Mathematical equations can be used just like in
+[Markdown cells of notebooks](markdown-cells.ipynb#Equations).
+
+Inline like this: $\text{e}^{i\pi} = -1$.
+
+
+## Tables
+
+A     | B     | A and B
+------|-------|--------
+False | False | False
+True  | False | False
+False | True  | False
+True  | True  | True
+
+
+## Images
+
+![Jupyter notebook icon](images/notebook_icon.png)

doc/index.rst

@@ -37,6 +37,8 @@ __ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
     custom-css
     a-normal-rst-file
     a-markdown-file
+    a-markdown-file-inline
+    a-markdown-file-block
     links
     contributing
     references

doc/requirements.txt

@@ -11,5 +11,6 @@ sphinxcontrib-bibtex>=2.1
 sphinxcontrib-svg2pdfconverter
 ipywidgets
 jupytext
+sphinx == 8.2.0rc1
 sphinx-last-updated-by-git
 sphinx-codeautolink

src/nbsphinx/__init__.py

@@ -27,7 +27,9 @@
 import sphinx.directives.other
 import sphinx.environment
 import sphinx.errors
+import sphinx.transforms
 import sphinx.transforms.post_transforms.images
+import sphinx.util.console
 from sphinx.util.matching import patmatch
 try:
     from sphinx.util.display import status_iterator
@@ -1458,7 +1460,7 @@ def apply(self):
             env.nbsphinx_files.setdefault(env.docname, []).append(file)
 
 
-class ForceEquations(docutils.transforms.Transform):
+class ForceEquations(sphinx.transforms.SphinxTransform):
     """Unconditionally enable equations on notebooks.
 
     Except if ``nbsphinx_assume_equations`` is set to ``False``.
@@ -1468,9 +1470,15 @@ class ForceEquations(docutils.transforms.Transform):
     default_priority = 900  # after checking for equations in MathDomain
 
     def apply(self):
-        env = self.document.settings.env
-        if env.config.nbsphinx_assume_equations:
-            env.get_domain('math').data['has_equations'][env.docname] = True
+        if sphinx.version_info[:2] >= (8, 2):
+            # Sphinx 8.2 detects equations via the writer/translator,
+            # so ForceEquations isn't needed.
+            return
+        if not self.config.nbsphinx_assume_equations:
+            return
+
+        maths_data = self.env.get_domain('math').data
+        maths_data.setdefault('has_equations', {})[self.env.docname] = True
 
 
 class GetSizeFromImages(