Running doctests using doctest-plus

docs/conf.py

@@ -46,7 +46,6 @@
 extensions = [
     # Sphinx extensions
     "sphinx.ext.autodoc",
-    "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
@@ -73,10 +72,6 @@
 napoleon_use_rtype = True
 napoleon_google_docstring = False
 
-doctest_global_setup = """
-from docs import *
-import pybamm
-"""
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/source/user_guide/installation/index.rst

@@ -144,9 +144,10 @@ Dependency
 `pre-commit <https://pre-commit.com/index.html>`__                               \-                 dev                For managing and maintaining multi-language pre-commit hooks.
 `ruff <https://beta.ruff.rs/docs/>`__                                            \-                 dev                For code formatting.
 `nox <https://nox.thea.codes/en/stable/>`__                                      \-                 dev                For running testing sessions in multiple environments.
-`coverage <https://coverage.readthedocs.io/en/>`__                               \-                 dev                For calculating coverage of tests.
+`pytest-cov <https://pytest-cov.readthedocs.io/en/latest/>`__                    \-                 dev                For calculating coverage of tests.
 `parameterized <https://github.com/wolever/parameterized>`__                     \-                 dev                For test parameterization.
-`pytest <https://docs.pytest.org/en/stable/>`__                                  6.0.0              dev                For running Jupyter notebooks tests.
+`pytest <https://docs.pytest.org/en/stable/>`__                                  6.0.0              dev                For running Unit, Integration and Jupyter notebooks tests.
+`pytest-doctestplus <https://github.com/scientific-python/pytest-doctestplus>`__ \-                 dev                For running doctests.
 `pytest-xdist <https://pytest-xdist.readthedocs.io/en/latest/>`__                \-                 dev                For running tests in parallel across distributed workers.
 `nbmake <https://github.com/treebeardtech/nbmake/>`__                            \-                 dev                A ``pytest`` plugin for executing Jupyter notebooks.
 ================================================================================ ================== ================== =============================================================

pybamm/expression_tree/operations/latexify.py

@@ -38,16 +38,16 @@ class Latexify:
     >>> model = pybamm.lithium_ion.SPM()
 
     This will returns all model equations in png
-    >>> model.latexify("equations.png")
+    >>> model.latexify("equations.png") # doctest: +SKIP
 
     This will return all the model equations in latex
-    >>> model.latexify()
+    >>> model.latexify() # doctest: +SKIP
 
     This will return the list of all the model equations
-    >>> model.latexify(newline=False)
+    >>> model.latexify(newline=False) # doctest: +SKIP
 
     This will return first five model equations
-    >>> model.latexify(newline=False)[1:5]
+    >>> model.latexify(newline=False)[1:5] # doctest: +SKIP
     """
 
     def __init__(self, model, filename: str | None = None, newline: bool = True):

pybamm/models/base_model.py

@@ -1345,16 +1345,16 @@ def latexify(self, filename=None, newline=True, output_variables=None):
         >>> model = pybamm.lithium_ion.SPM()
 
         This will returns all model equations in png
-        >>> model.latexify("equations.png")
+        >>> model.latexify("equations.png") # doctest: +SKIP
 
         This will return all the model equations in latex
-        >>> model.latexify()
+        >>> model.latexify() # doctest: +SKIP
 
         This will return the list of all the model equations
-        >>> model.latexify(newline=False)
+        >>> model.latexify(newline=False) # doctest: +SKIP
 
         This will return first five model equations
-        >>> model.latexify(newline=False)[1:5]
+        >>> model.latexify(newline=False)[1:5] # doctest: +SKIP
         """
         from pybamm.expression_tree.operations.latexify import Latexify
 

pybamm/models/full_battery_models/lithium_metal/dfn.py

@@ -2,7 +2,7 @@
 # Doyle-Fuller-Newman (DFN) Model
 #
 import pybamm
-from ..lithium_ion.dfn import DFN as LithiumIonDFN
+from pybamm.models.full_battery_models.lithium_ion.dfn import DFN as LithiumIonDFN
 
 
 class DFN(LithiumIonDFN):

pybamm/parameters/parameter_sets.py

@@ -17,6 +17,7 @@ class ParameterSets(Mapping):
 
     .. doctest::
 
+        >>> import pybamm
         >>> list(pybamm.parameter_sets)
         ['Ai2020', 'Chen2020', ...]
 

pyproject.toml

@@ -103,6 +103,8 @@ dev = [
     "nox",
     # For coverage
     "pytest-cov",
+    # For doctest
+    "pytest-doctestplus",
     # For test parameterization
     "parameterized>=0.9",
     # For testing Jupyter notebooks

run-tests.py

@@ -6,7 +6,6 @@
 # (see https://github.com/pints-team/pints)
 #
 import os
-import shutil
 import pybamm
 import sys
 import argparse
@@ -61,32 +60,21 @@ def run_doc_tests():
     Checks if the documentation can be built, runs any doctests (currently not
     used).
     """
-    print("Checking if docs can be built.")
+    print("Checking for doctests.")
     try:
         subprocess.run(
             [
-                "sphinx-build",
-                "-j",
-                "auto",
-                "-b",
-                "doctest",
-                "docs",
-                "docs/build/html",
-                "-W",
-                "--keep-going",
+                f"{sys.executable}",
+                "-m",
+                "pytest",
+                "--doctest-plus",
+                "pybamm",
             ],
             check=True,
         )
     except subprocess.CalledProcessError as e:
         print(f"FAILED with exit code {e.returncode}")
         sys.exit(e.returncode)
-    finally:
-        # Regardless of whether the doctests pass or fail, attempt to remove the built files.
-        print("Deleting built files.")
-        try:
-            shutil.rmtree("docs/build/html/.doctrees/")
-        except Exception as e:
-            print(f"Error deleting built files: {e}")
 
 
 def run_scripts(executable="python"):