Updated readthedocs.yml to linkcheck

.readthedocs.yaml

@@ -21,6 +21,8 @@ build:
   tools:
     python: "3.12"
   jobs:
+    pre_build:
+      - python -m sphinx -b linkcheck -D linkcheck_timeout=5 docs/ ./linkcheck_output
     # Unshallow the git clone otherwise this may cause issues with Sphinx extensions
     post_checkout:
       - git fetch --unshallow

docs/conf.py

@@ -85,6 +85,16 @@
 # The master toctree document.
 master_doc = "index"
 
+# Ignoring links from ScienceDirect
+linkcheck_ignore = [
+    "https://www.sciencedirect.com",
+    "https://doi.org/10.1137/20M1336898",  # DOI link to ignore
+    "https://en.wikipedia.org/wiki/",  # Wikipedia link to ignore
+    "https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md#a-before-you-begin",  # GitHub link to ignore
+    "https://books.google.co.uk/books",
+]
+
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

docs/index.rst

@@ -22,7 +22,7 @@ PyBaMM documentation
 
 **Useful links**:
 `Project Home Page <https://www.pybamm.org>`_ |
-`Installation <source/user_guide/installation/index.html>`_ |
+`Installation <source/user_guide/installation/index.rst>`_ |
 `Source Repository <https://github.com/pybamm-team/pybamm>`_ |
 `Issue Tracker <https://github.com/pybamm-team/pybamm/issues>`_ |
 `Discussions <https://pybamm.discourse.group/>`_
@@ -107,7 +107,7 @@ explore the effect of different battery designs and modeling assumptions under a
 
       +++
 
-      .. button-link:: source/user_guide/contributing.html
+      .. button-link:: ../CONTRIBUTING.md
          :expand:
          :color: secondary
          :click-parent:

docs/source/user_guide/installation/gnu-linux-mac.rst

@@ -84,13 +84,15 @@ library beforehand.
 
       conda install -c conda-forge pybamm-base
 
-PyBaMM’s `required dependencies <index.html#install-required-dependencies>`_
+PyBaMM’s :ref:`required dependencies <install-required-dependencies>`
+
 (such as ``numpy``, ``casadi``, etc) will be installed automatically when you
 install ``pybamm`` using ``pip`` or ``pybamm-base`` using ``conda``.
 
 For an introduction to virtual environments, see
 (https://realpython.com/python-virtual-environments-a-primer/).
 
+.. _optional-jaxsolver:
 
 Optional - JaxSolver
 ~~~~~~~~~~~~~~~~~~~~
@@ -103,7 +105,7 @@ Users can install ``jax`` and ``jaxlib`` to use the Jax solver.
 
 The ``pip install "pybamm[jax]"`` command automatically downloads and installs ``pybamm`` and the compatible versions of ``jax`` and ``jaxlib`` on your system.
 
-PyBaMM's full `conda-forge distribution <index.html#installation>`_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default.
+PyBaMM's full `conda-forge distribution <index.rst#installation>`_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default.
 
 .. _optional-iree-mlir-support:
 

docs/source/user_guide/installation/index.rst

@@ -1,6 +1,14 @@
+
+
+Required dependencies
+=====================
+
+PyBaMM requires the following dependencies.
+
 Installation
 ============
 
+
 PyBaMM is available on GNU/Linux, MacOS and Windows.
 It can be installed using ``pip`` or ``conda``, or from source.
 
@@ -16,7 +24,7 @@ It can be installed using ``pip`` or ``conda``, or from source.
 
    PyBaMM is available as a ``conda`` package through the conda-forge channel.
 
-   The ``pybamm`` package on conda-forge installs PyBaMM with all the `required and optional dependencies <index.html#dependencies>`_ available on conda-forge.
+   The ``pybamm`` package on conda-forge installs PyBaMM with all the `required and optional dependencies <#dependencies>`_ available on conda-forge.
 
    .. note::
 
@@ -26,7 +34,7 @@ It can be installed using ``pip`` or ``conda``, or from source.
 
       conda install -c conda-forge pybamm
 
-   The ``pybamm-base`` package installs PyBaMM only with its `required dependencies <index.html#install-required-dependencies>`_.
+        The ``pybamm-base`` package installs PyBaMM only with its `required dependencies <#install-required-dependencies>`_.
 
    .. code:: bash
 
@@ -38,19 +46,23 @@ Optional solvers
 
 The following solvers are optionally available:
 
-*  `jax <https://jax.readthedocs.io/en/latest/notebooks/quickstart.html>`_ -based solver, see `Optional - JaxSolver <gnu-linux-mac.html#optional-jaxsolver>`_.
-*  `IREE <https://iree.dev/>`_ (`MLIR <https://mlir.llvm.org/>`_) support, see `Optional - IREE / MLIR Support <gnu-linux-mac.html#optional-iree-mlir-support>`_.
+*  `jax <https://jax.readthedocs.io/en/latest/notebooks/quickstart.html>`_ -based solver, see :ref:`optional-jaxsolver` .
+*  `IREE <https://iree.dev/>`_ (`MLIR <https://mlir.llvm.org/>`_) support, see :ref:`optional-iree-mlir-support`.
 
 Dependencies
-------------
-.. _install.required_dependencies:
+============
+pybamm requires the following dependencies:
 
 .. warning::
 
     The list of dependencies below might be outdated. Please refer to the ``pyproject.toml`` file to find all dependencies.
 
+.. _install-required-dependencies:
+
+
 Required dependencies
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
+
 
 PyBaMM requires the following dependencies.
 
@@ -74,7 +86,7 @@ Package                                                             Minimum supp
 .. _install.optional_dependencies:
 
 Optional Dependencies
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
 
 PyBaMM has a number of optional dependencies for different functionalities.
 If the optional dependency is not installed, PyBaMM will raise an ImportError when the method requiring that dependency is called.
@@ -86,7 +98,7 @@ and specific sets of dependencies are listed in the sections below.
 .. _install.plot_dependencies:
 
 Plot dependencies
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Installable with ``pip install "pybamm[plot]"``
 
@@ -100,7 +112,7 @@ Dependency                                                  Minimum Version    p
 .. _install.docs_dependencies:
 
 Docs dependencies
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Installable with ``pip install "pybamm[docs]"``
 
@@ -128,7 +140,7 @@ Dependency
 .. _install.examples_dependencies:
 
 Examples dependencies
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
 Installable with ``pip install "pybamm[examples]"``
 
@@ -141,7 +153,7 @@ Dependency
 .. _install.dev_dependencies:
 
 Dev dependencies
-^^^^^^^^^^^^^^^^^
+----------------
 
 Installable with ``pip install "pybamm[dev]"``
 
@@ -164,7 +176,7 @@ Dependency
 .. _install.cite_dependencies:
 
 Cite dependencies
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Installable with ``pip install "pybamm[cite]"``
 
@@ -177,7 +189,8 @@ Dependency                                                  Minimum Version    p
 .. _install.bpx_dependencies:
 
 bpx dependencies
-^^^^^^^^^^^^^^^^^
+----------------
+
 
 Installable with ``pip install "pybamm[bpx]"``
 
@@ -190,7 +203,7 @@ Dependency                                                  Minimum Version    p
 .. _install.tqdm_dependencies:
 
 tqdm dependencies
-^^^^^^^^^^^^^^^^^
+-----------------
 
 Installable with ``pip install "pybamm[tqdm]"``
 
@@ -203,7 +216,7 @@ Dependency                                                  Minimum Version    p
 .. _install.jax_dependencies:
 
 Jax dependencies
-^^^^^^^^^^^^^^^^^
+----------------
 
 Installable with ``pip install "pybamm[jax]"``, currently supported on Python 3.9-3.11.
 
@@ -215,7 +228,7 @@ Dependency                                                                Minimu
 ========================================================================= ================== ================== =======================
 
 IREE dependencies
-^^^^^^^^^^^^^^^^^^
+-----------------
 
 Installable with ``pip install "pybamm[iree]"`` (requires ``jax`` dependencies to be installed).
 
@@ -226,7 +239,7 @@ Dependency                                                                Minimu
 ========================================================================= ================== ================== =======================
 
 Full installation guide
------------------------
+=======================
 
 Installing a specific version? Installing from source? Check the advanced installation pages below
 

docs/source/user_guide/installation/install-from-source.rst

@@ -1,6 +1,9 @@
+.. _install-from-source:
+
 Install from source (GNU Linux and macOS)
 =========================================
 
+
 .. contents::
 
 This page describes the build and installation of PyBaMM from the source code, available on GitHub. Note that this is **not the recommended approach for most users** and should be reserved to people wanting to participate in the development of PyBaMM, or people who really need to use bleeding-edge feature(s) not yet available in the latest released version. If you do not fall in the two previous categories, you would be better off installing PyBaMM using pip or conda.

docs/source/user_guide/installation/windows-wsl.rst

@@ -37,7 +37,7 @@ Get PyBaMM's Source Code
 5. Follow the Installation Steps
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Follow the `installation instructions for PyBaMM on Linux <install-from-source.html>`__.
+Follow the :ref:`installation instructions for PyBaMM on Linux <install-from-source>`.
 
 Using Visual Studio Code with the WSL
 ---------------------------------------

docs/source/user_guide/installation/windows.rst

@@ -73,7 +73,8 @@ PyBaMM can be installed via pip:
 
       conda install -c conda-forge pybamm-base
 
-PyBaMM’s `required dependencies <index.html#install-required-dependencies>`_
+PyBaMM’s :ref:`required dependencies <install-required-dependencies>`
+
 (such as ``numpy``, ``casadi``, etc) will be installed automatically when you
 install ``pybamm`` using ``pip`` or ``pybamm-base`` using ``conda``.
 
@@ -91,7 +92,7 @@ Users can install ``jax`` and ``jaxlib`` to use the Jax solver.
 
 The ``pip install "pybamm[jax]"`` command automatically downloads and installs ``pybamm`` and the compatible versions of ``jax`` and ``jaxlib`` on your system.
 
-PyBaMM's full `conda-forge distribution <index.html#installation>`_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default.
+PyBaMM's full `conda-forge distribution <index.rst#installation>`_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default.
 
 Uninstall PyBaMM
 ----------------
@@ -109,4 +110,4 @@ Installation using WSL
 
 If you want to install the optional PyBaMM solvers, you have to use the
 Windows Subsystem for Linux (WSL). You can find the installation
-instructions `here <windows-wsl.html>`__.
+`Installation <windows-wsl.rst>`_