diff --git a/.readthedocs.yaml b/.readthedocs.yaml index ae6a74a5cf..c90f880eac 100644 --- 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 index 76dcffb18b..6db314724a 100644 --- 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 index 2ea894e89a..0d77b17ee9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -22,7 +22,7 @@ PyBaMM documentation **Useful links**: `Project Home Page `_ | -`Installation `_ | +`Installation `_ | `Source Repository `_ | `Issue Tracker `_ | `Discussions `_ @@ -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 index 78e1a161b4..80d3269693 100644 --- 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 index 877462b5ac..73e2e76029 100644 --- 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 `_ +PyBaMM’s :ref:`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 `_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default. +PyBaMM's full `conda-forge distribution `_ (``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 index 8920f3f35e..4cbced26bd 100644 --- 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 `_ 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 `_. + 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 `_ -based solver, see `Optional - JaxSolver `_. -* `IREE `_ (`MLIR `_) support, see `Optional - IREE / MLIR Support `_. +* `jax `_ -based solver, see :ref:`optional-jaxsolver` . +* `IREE `_ (`MLIR `_) 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 index f4d60ee9a8..373d240a58 100644 --- 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 index 2f0f5a7bad..8aefc20d4b 100644 --- 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 `__. +Follow the :ref:`installation instructions for PyBaMM on Linux `. 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 index 5e7405abb4..61e268a078 100644 --- 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 `_ +PyBaMM’s :ref:`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 `_ (``pybamm``) includes ``jax`` and ``jaxlib`` by default. +PyBaMM's full `conda-forge distribution `_ (``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 `__. +instructions on the `Installation `_ page.