Updated readthedocs.yml to linkcheck (#4712)

* Updated readthedocs.yml to linkcheck * Link ignoring added to the conf.py * Path updated for the output log files in linkcheck * Internal links fixed * External links fixed * Resolved heading inconistency * Headings Adjusted Attempt1 * Fixed refs * linkcheck timeout adjusted to 5 * updated installation/index.rst * Headers of installation/index.rst reverted * Update docs/source/user_guide/installation/index.rst Co-authored-by: Agriya Khetarpal <[email protected]> * Update docs/source/user_guide/installation/windows.rst Co-authored-by: Agriya Khetarpal <[email protected]> * PyBaMM github link modifies --------- Co-authored-by: Agriya Khetarpal <[email protected]>
pybamm-team · Dec 27, 2024 · b9aebdc · b9aebdc
1 parent a362f92
commit b9aebdc
Show file tree

Hide file tree

Showing 9 changed files with 42 additions and 18 deletions.
diff --git a/.readthedocs.yaml b/.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

diff --git a/docs/conf.py b/docs/conf.py
@@ -85,6 +85,15 @@
 # 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://books.google.co.uk/books",
+]
+
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

diff --git a/docs/index.rst b/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:

diff --git a/docs/source/examples/notebooks/spatial_methods/finite-volumes.ipynb b/docs/source/examples/notebooks/spatial_methods/finite-volumes.ipynb
@@ -1283,7 +1283,7 @@
     "- Gradient and divergence of microscale variables in the P2D model\n",
     "- Indefinite integral\n",
     "\n",
-    "If you would like detailed examples of these operations, please [create an issue](https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md#a-before-you-begin) and we will be happy to help."
+    "If you would like detailed examples of these operations, please [create an issue](https://docs.pybamm.org/en/latest/source/user_guide/contributing.html#a-before-you-begin) and we will be happy to help."
    ]
   },
   {

diff --git a/docs/source/user_guide/installation/gnu-linux-mac.rst b/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:
 

diff --git a/docs/source/user_guide/installation/index.rst b/docs/source/user_guide/installation/index.rst
@@ -1,6 +1,7 @@
 Installation
 ============
 
+
 PyBaMM is available on GNU/Linux, MacOS and Windows.
 It can be installed using ``pip`` or ``conda``, or from source.
 
@@ -16,7 +17,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 +27,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,20 +39,25 @@ 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.
 
 =================================================================== ==========================
@@ -141,7 +147,7 @@ Dependency
 .. _install.dev_dependencies:
 
 Dev dependencies
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 
 Installable with ``pip install "pybamm[dev]"``
 
@@ -177,7 +183,8 @@ Dependency                                                  Minimum Version    p
 .. _install.bpx_dependencies:
 
 bpx dependencies
-^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
+
 
 Installable with ``pip install "pybamm[bpx]"``
 
@@ -203,7 +210,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 +222,7 @@ Dependency                                                                Minimu
 ========================================================================= ================== ================== =======================
 
 IREE dependencies
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^
 
 Installable with ``pip install "pybamm[iree]"`` (requires ``jax`` dependencies to be installed).
 

diff --git a/docs/source/user_guide/installation/install-from-source.rst b/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.

diff --git a/docs/source/user_guide/installation/windows-wsl.rst b/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
 ---------------------------------------

diff --git a/docs/source/user_guide/installation/windows.rst b/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>`__.
+instructions on the `Installation <windows-wsl.rst>`_ page.