executablebooks · mmcky · Aug 25, 2021 · Aug 25, 2021 · Aug 25, 2021 · Aug 25, 2021
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -27,7 +27,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: [3.6, 3.7, 3.8, 3.9]
-        sphinx: [">=3,<4"]
+        sphinx: [">=3,<5"]
         include:
           - os: ubuntu-latest
             python-version: 3.8

diff --git a/setup.cfg b/setup.cfg
@@ -38,17 +38,17 @@ project_urls =
 [options]
 packages = find:
 install_requires =
-    docutils>=0.15
+    docutils>=0.15,<0.17
     importlib_metadata
     ipython
     ipywidgets>=7.0.0,<8
     jupyter-cache~=0.4.1
     jupyter_sphinx~=0.3.2
-    myst-parser~=0.14.0
+    myst-parser~=0.15.1
     nbconvert>=5.6,<7
     nbformat~=5.0
     pyyaml
-    sphinx>=2,<4
+    sphinx>=2,<5
     sphinx-togglebutton~=0.2.2
 python_requires = >=3.6
 include_package_data = True

diff --git a/tests/conftest.py b/tests/conftest.py
@@ -5,6 +5,7 @@
 
 import nbformat as nbf
 import pytest
+import sphinx
 from docutils.nodes import image as image_node
 from nbconvert.filters import strip_ansi
 from nbdime.diffing.notebooks import (
@@ -60,6 +61,9 @@ def __init__(self, app, filenames):
         self.app = app
         self.env = app.env
         self.files = [os.path.splitext(ff) for ff in filenames]
+        self.software_versions = (
+            f".sphinx{sphinx.version_info[0]}"  # encodes sphinx major version
+        )
 
         # self.nb_file = nb_file
         # self.nb_name = os.path.splitext(nb_file)[0]
@@ -102,23 +106,28 @@ def get_doctree(self, docname=None):
     def get_html(self, index=0):
         """Return the built HTML file."""
         name = self.files[index][0]
-        _path = self.app.outdir / (name + ".html")
+        _path = self.app.outdir / (name + self.software_versions + ".html")
         if not _path.exists():
             pytest.fail("html not output")
         return read_text(_path)
 
     def get_nb(self, index=0):
         """Return the output notebook (after any execution)."""
         name = self.files[index][0]
-        _path = self.app.srcdir / "_build" / "jupyter_execute" / (name + ".ipynb")
+        _path = (
+            self.app.srcdir
+            / "_build"
+            / "jupyter_execute"
+            / (name + self.software_versions + ".ipynb")
+        )
         if not _path.exists():
             pytest.fail("notebook not output")
         return read_text(_path)
 
     def get_report_file(self, index=0):
         """Return the report file for a failed execution."""
         name = self.files[index][0]
-        _path = self.app.outdir / "reports" / (name + ".log")
+        _path = self.app.outdir / "reports" / (name + self.software_versions + ".log")
         if not _path.exists():
             pytest.fail("report log not output")
         return read_text(_path)

diff --git a/tests/test_parser.py b/tests/test_parser.py
@@ -18,7 +18,9 @@ def test_basic_run(sphinx_run, file_regression):
         == '{"display_name": "Python 3", "language": "python", "name": "python3"}'
     )
     file_regression.check(
-        sphinx_run.get_doctree().pformat(), extension=".xml", encoding="utf8"
+        sphinx_run.get_doctree().pformat(),
+        extension=f"{sphinx_run.software_versions}.xml",
+        encoding="utf8",
     )
 
     filenames = {
@@ -56,7 +58,9 @@ def test_complex_outputs(sphinx_run, file_regression):
         == '{"display_name": "Python 3", "language": "python", "name": "python3"}'
     )
     file_regression.check(
-        sphinx_run.get_doctree().pformat(), extension=".xml", encoding="utf8"
+        sphinx_run.get_doctree().pformat(),
+        extension=f"{sphinx_run.software_versions}.xml",
+        encoding="utf8",
     )
 
     filenames = {
@@ -85,6 +89,7 @@ def test_toctree_in_ipynb(sphinx_run, file_regression):
     print(sphinx_run.status())
     print(sphinx_run.warnings())
     file_regression.check(
-        sphinx_run.get_doctree("latex_build/other").pformat(), extension=".xml"
+        sphinx_run.get_doctree("latex_build/other").pformat(),
+        extension=f"{sphinx_run.software_versions}.xml",
     )
     assert sphinx_run.warnings() == ""
diff --git a/tests/test_parser/test_basic_run.xml → tests/test_parser/test_basic_run.sphinx3.xml b/tests/test_parser/test_basic_run.xml → tests/test_parser/test_basic_run.sphinx3.xml
@@ -1,5 +1,5 @@
 <document source="basic_run">
-    <section ids="a-title" names="a\ title">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="a-title" names="a\ title">
         <title>
             a title
         <paragraph>

diff --git a/tests/test_parser/test_basic_run.sphinx4.xml b/tests/test_parser/test_basic_run.sphinx4.xml
@@ -0,0 +1,13 @@
+<document source="basic_run">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="a-title" names="a\ title">
+        <title>
+            a title
+        <paragraph>
+            some text
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    a=1
+                    print(a)
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
diff --git a/tests/test_parser/test_complex_outputs.xml → ...t_parser/test_complex_outputs.sphinx3.xml b/tests/test_parser/test_complex_outputs.xml → ...t_parser/test_complex_outputs.sphinx3.xml
@@ -9,7 +9,7 @@
                 sym.init_printing(use_latex=True)
                 import numpy as np
                 from IPython.display import Image, Latex
-    <section ids="markdown" names="markdown">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="markdown" names="markdown">
         <title>
             Markdown
         <section ids="general" names="general">
@@ -84,7 +84,7 @@
                 \todo[inline]{an inline todo}
             <paragraph>
                 Some text.\todo{a todo in the margins}
-    <section ids="text-output" names="text\ output">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="text-output" names="text\ output">
         <title>
             Text Output
         <CellNode cell_type="code" classes="cell">
@@ -96,7 +96,7 @@
                     """)
             <CellOutputNode classes="cell_output">
                 <CellOutputBundleNode output_count="1">
-    <section ids="images-and-figures" names="images\ and\ figures">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="images-and-figures" names="images\ and\ figures">
         <title>
             Images and Figures
         <CellNode cell_type="code" classes="cell">
@@ -121,7 +121,7 @@
                         plt.legend();
                 <CellOutputNode classes="cell_output">
                     <CellOutputBundleNode output_count="1">
-    <section ids="tables-with-pandas" names="tables\ (with\ pandas)">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="tables-with-pandas" names="tables\ (with\ pandas)">
         <title>
             Tables (with pandas)
         <paragraph>
@@ -136,7 +136,7 @@
                     df.round(3)
             <CellOutputNode classes="cell_output">
                 <CellOutputBundleNode output_count="1">
-    <section ids="equations-with-ipython-or-sympy" names="equations\ (with\ ipython\ or\ sympy)">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="equations-with-ipython-or-sympy" names="equations\ (with\ ipython\ or\ sympy)">
         <title>
             Equations (with ipython or sympy)
         <CellNode cell_type="code" classes="cell">

diff --git a/tests/test_parser/test_complex_outputs.sphinx4.xml b/tests/test_parser/test_complex_outputs.sphinx4.xml
@@ -0,0 +1,165 @@
+<document source="complex_outputs">
+    <CellNode cell_type="code" classes="cell">
+        <CellInputNode classes="cell_input">
+            <literal_block language="ipython3" xml:space="preserve">
+                import matplotlib.pyplot as plt
+                import pandas as pd
+                pd.set_option('display.latex.repr', True)
+                import sympy as sym
+                sym.init_printing(use_latex=True)
+                import numpy as np
+                from IPython.display import Image, Latex
+    <section classes="tex2jax_ignore mathjax_ignore" ids="markdown" names="markdown">
+        <title>
+            Markdown
+        <section ids="general" names="general">
+            <title>
+                General
+            <paragraph>
+                Some markdown text.
+            <paragraph>
+                A list:
+            <bullet_list>
+                <list_item>
+                    <paragraph>
+                        something
+                <list_item>
+                    <paragraph>
+                        something else
+            <paragraph>
+                A numbered list
+            <enumerated_list>
+                <list_item>
+                    <paragraph>
+                        something
+                <list_item>
+                    <paragraph>
+                        something else
+            <paragraph>
+                non-ascii characters TODO
+            <paragraph>
+                This is a long section of text, which we only want in a document (not a presentation)
+
+                some text
+
+                some more text
+
+                some more text
+
+                some more text
+
+                some more text
+
+                some more text
+
+                some more text
+
+                some more text
+
+                some more text
+            <paragraph>
+                This is an abbreviated section of the document text, which we only want in a presentation
+            <bullet_list>
+                <list_item>
+                    <paragraph>
+                        summary of document text
+        <section ids="references-and-citations" names="references\ and\ citations">
+            <title>
+                References and Citations
+            <paragraph>
+                References to \cref{fig:example}, \cref{tbl:example}, =@eqn:example_sympy and \cref{code:example_mpl}.
+            <paragraph>
+                A latex citation.\cite{zelenyak_molecular_2016}
+            <paragraph>
+                A html citation.
+                <raw format="html" xml:space="preserve">
+                    <cite data-cite="kirkeminde_thermodynamic_2012">
+                (Kirkeminde, 2012)
+                <raw format="html" xml:space="preserve">
+                    </cite>
+        <section ids="todo-notes" names="todo\ notes">
+            <title>
+                Todo notes
+            <paragraph>
+                \todo[inline]{an inline todo}
+            <paragraph>
+                Some text.\todo{a todo in the margins}
+    <section classes="tex2jax_ignore mathjax_ignore" ids="text-output" names="text\ output">
+        <title>
+            Text Output
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    print("""
+                    This is some printed text,
+                    with a nicely formatted output.
+                    """)
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="images-and-figures" names="images\ and\ figures">
+        <title>
+            Images and Figures
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    Image('example.jpg',height=400)
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
+        <section ids="displaying-a-plot-with-its-code" names="displaying\ a\ plot\ with\ its\ code">
+            <title>
+                Displaying a plot with its code
+            <paragraph>
+                A matplotlib figure, with the caption set in the markdowncell above the figure.
+            <paragraph>
+                The plotting code for a matplotlib figure (\cref{fig:example_mpl}).
+            <CellNode cell_type="code" classes="cell">
+                <CellInputNode classes="cell_input">
+                    <literal_block language="ipython3" xml:space="preserve">
+                        plt.scatter(np.random.rand(10), np.random.rand(10), 
+                                    label='data label')
+                        plt.ylabel(r'a y label with latex $\alpha$')
+                        plt.legend();
+                <CellOutputNode classes="cell_output">
+                    <CellOutputBundleNode output_count="1">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="tables-with-pandas" names="tables\ (with\ pandas)">
+        <title>
+            Tables (with pandas)
+        <paragraph>
+            The plotting code for a pandas Dataframe table (\cref{tbl:example}).
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    df = pd.DataFrame(np.random.rand(3,4),columns=['a','b','c','d'])
+                    df.a = ['$\delta$','x','y']
+                    df.b = ['l','m','n']
+                    df.set_index(['a','b'])
+                    df.round(3)
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="equations-with-ipython-or-sympy" names="equations\ (with\ ipython\ or\ sympy)">
+        <title>
+            Equations (with ipython or sympy)
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    Latex('$$ a = b+c $$')
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
+        <paragraph>
+            The plotting code for a sympy equation (=@eqn:example_sympy).
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    y = sym.Function('y')
+                    n = sym.symbols(r'\alpha')
+                    f = y(n)-2*y(n-1/sym.pi)-5*y(n-2)
+                    sym.rsolve(f,y(n),[1,4])
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    from IPython.display import display, Markdown
+                    display(Markdown('**_some_ markdown**'))
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
diff --git a/tests/test_parser/test_toctree_in_ipynb.xml → ..._parser/test_toctree_in_ipynb.sphinx3.xml b/tests/test_parser/test_toctree_in_ipynb.xml → ..._parser/test_toctree_in_ipynb.sphinx3.xml
@@ -1,6 +1,6 @@
 <document source="latex_build/other">
     <target refid="title-ref">
-    <section ids="title title-ref" names="title title_ref">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="title title-ref" names="title title_ref">
         <title refid="id1">
             Title
         <topic classes="contents" ids="contents" names="contents">

diff --git a/tests/test_parser/test_toctree_in_ipynb.sphinx4.xml b/tests/test_parser/test_toctree_in_ipynb.sphinx4.xml
@@ -0,0 +1,21 @@
+<document source="latex_build/other">
+    <target refid="title-ref">
+    <section classes="tex2jax_ignore mathjax_ignore" ids="title title-ref" names="title title_ref">
+        <title refid="id1">
+            Title
+        <topic classes="contents" ids="contents" names="contents">
+            <title>
+                Contents
+            <bullet_list>
+                <list_item>
+                    <paragraph>
+                        <reference ids="id1" refid="title">
+                            Title
+        <paragraph>
+            Content
+        <CellNode cell_type="code" classes="cell">
+            <CellInputNode classes="cell_input">
+                <literal_block language="ipython3" xml:space="preserve">
+                    print(1)
+            <CellOutputNode classes="cell_output">
+                <CellOutputBundleNode output_count="1">
diff --git a/tox.ini b/tox.ini
@@ -13,11 +13,12 @@
 [tox]
 envlist = py37-sphinx3
 
-[testenv:py{36,37,38,39}-sphinx{2,3}]
+[testenv:py{36,37,38,39}-sphinx{2,3,4}]
 extras = testing
 deps =
     sphinx2: sphinx>=2,<3
     sphinx3: sphinx>=3,<4
+    sphinx4: sphinx>=4,<5
 commands = pytest {posargs}
 
 [testenv:docs-{update,clean}]