From 4b7ededbadf272c45eee19c176ef841a1a3d099e Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 16:44:29 +0530
Subject: [PATCH 01/19] Add conditions based on terminal commands to
 selectively exclude outputs

---
 docs/conf.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index 336fa15743..d0b1683aff 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -203,6 +203,15 @@
 
 # -- Options for LaTeX output ------------------------------------------------
 
+# Note: we exclude the examples directory from the LaTeX build because it has
+# problems with the creation of PDFs on Read the Docs
+# https://github.com/readthedocs/readthedocs.org/issues/2045
+
+# Detect if we are building LaTeX output through the invocation of the build commands
+if any("latex" in arg for arg in sys.argv) or any("latexmk" in arg for arg in sys.argv):
+    exclude_patterns.append("source/examples/*")
+    print("Skipping compilation of .ipynb files for LaTeX build.")
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #

From 94c1cfc78f9f36b99ae3463b034246c837f08ab0 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 16:45:10 +0530
Subject: [PATCH 02/19] Add explainer about notebooks in PDF builds

---
 docs/source/user_guide/index.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/source/user_guide/index.md b/docs/source/user_guide/index.md
index 2ed483a9b2..f7bc57a414 100644
--- a/docs/source/user_guide/index.md
+++ b/docs/source/user_guide/index.md
@@ -25,9 +25,13 @@ fundamentals/index
 
 # Example notebooks
 
-The notebooks below provide a good introduction to PyBaMM and how to use it. For more
-examples, see the [Examples](../examples/index.rst) section.
+PyBaMM ships with example notebooks that demonstrate how to use it and reveal some of its
+functionalities and its inner workings. For more examples, see the [Examples](../examples/index.rst) section.
 
+```{only} latex
+The notebooks are not included in PDF formats of the documentation. You may access them on PyBaMM's hosted
+documentation available at https://docs.pybamm.org/en/latest/source/examples/index.html
+```
 
 ```{nbgallery}
 ---

From 2ec97c14f34f0f39d19e648ec9c99658a43b907a Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 17:44:12 +0530
Subject: [PATCH 03/19] Remove SVG files from LaTeX builds

---
 docs/index.rst | 103 +++++++++++++++++++++++++------------------------
 1 file changed, 53 insertions(+), 50 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 3e5d54ecb5..b2e0073780 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,77 +38,80 @@ Broadly, PyBaMM consists of
 Together, these enable flexible model definitions and fast battery simulations, allowing users to
 explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.
 
-.. grid:: 2
+.. SVG images sometimes cause LaTeX build errors
+.. only:: not latex
 
-   .. grid-item-card::
-      :img-top: _static/index-images/getting_started.svg
+   .. grid:: 2
 
-      User Guide
-      ^^^^^^^^^^
+      .. grid-item-card::
+         :img-top: _static/index-images/getting_started.svg
 
-      The user guide is the best place to start learning PyBaMM. It contains an installation
-      guide, an introduction to the main concepts and links to additional tutorials.
+         User Guide
+         ^^^^^^^^^^
 
-      +++
+         The user guide is the best place to start learning PyBaMM. It contains an installation
+         guide, an introduction to the main concepts and links to additional tutorials.
 
-      .. button-ref:: source/user_guide/index
-         :expand:
-         :color: secondary
-         :click-parent:
+         +++
 
-         To the user guide
+         .. button-ref:: source/user_guide/index
+            :expand:
+            :color: secondary
+            :click-parent:
 
-   .. grid-item-card::
-      :img-top: _static/index-images/examples.svg
+            To the user guide
 
-      Examples
-      ^^^^^^^^
+      .. grid-item-card::
+         :img-top: _static/index-images/examples.svg
 
-      Examples and tutorials can be viewed on the GitHub examples page,
-      which also provides a link to run them online through Google Colab.
+         Examples
+         ^^^^^^^^
 
-      +++
+         Examples and tutorials can be viewed on the GitHub examples page,
+         which also provides a link to run them online through Google Colab.
 
-      .. button-ref:: source/examples/index
-         :expand:
-         :color: secondary
-         :click-parent:
+         +++
 
-         To the examples
+         .. button-ref:: source/examples/index
+            :expand:
+            :color: secondary
+            :click-parent:
 
-   .. grid-item-card::
-      :img-top: _static/index-images/api.svg
+            To the examples
 
-      API Documentation
-      ^^^^^^^^^^^^^^^^^
+      .. grid-item-card::
+         :img-top: _static/index-images/api.svg
 
-      The reference guide contains a detailed description of the functions,
-      modules, and objects included in PyBaMM. The reference describes how the
-      methods work and which parameters can be used.
+         API Documentation
+         ^^^^^^^^^^^^^^^^^
 
-      +++
+         The reference guide contains a detailed description of the functions,
+         modules, and objects included in PyBaMM. The reference describes how the
+         methods work and which parameters can be used.
 
-      .. button-ref:: source/api/index
-         :expand:
-         :color: secondary
-         :click-parent:
+         +++
 
-         To the API documentation
+         .. button-ref:: source/api/index
+            :expand:
+            :color: secondary
+            :click-parent:
 
-   .. grid-item-card::
-      :img-top: _static/index-images/contributor.svg
+            To the API documentation
 
-      Contributor's Guide
-      ^^^^^^^^^^^^^^^^^^^
+      .. grid-item-card::
+         :img-top: _static/index-images/contributor.svg
 
-      Contributions to PyBaMM and its development are welcome! If you have ideas for
-      features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
+         Contributor's Guide
+         ^^^^^^^^^^^^^^^^^^^
 
-      +++
+         Contributions to PyBaMM and its development are welcome! If you have ideas for
+         features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
 
-      .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
-         :expand:
-         :color: secondary
-         :click-parent:
+         +++
 
-         To the contributor's guide
+         .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the contributor's guide

From 0caa9732ad6ceca270fb6f076f985c3ee9b8746b Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 22:54:12 +0530
Subject: [PATCH 04/19] Remove LaTeX output from `Extends:` labels

---
 docs/sphinxext/extend_parent.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/sphinxext/extend_parent.py b/docs/sphinxext/extend_parent.py
index 25978fe804..00752e1483 100644
--- a/docs/sphinxext/extend_parent.py
+++ b/docs/sphinxext/extend_parent.py
@@ -20,7 +20,8 @@ def process_docstring(app, what, name, obj, options, lines):
             # get the base class name
             base_cls_name = f"{getmro(obj)[1].__module__}.{getmro(obj)[1].__name__}"
             # add the extends keyword to the docstring
-            lines.append(f"**Extends:** :class:`{base_cls_name}`")
+            lines.append(".. only:: not latex\n")
+            lines.append(f"    **Extends:** :class:`{base_cls_name}`")
 
 
 def setup(app):

From 265cd4abf1120b992e48cffb69ce30ff822f33d6 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 23:09:17 +0530
Subject: [PATCH 05/19] Add temporary CI docs build job

---
 .github/workflows/test_on_push.yml | 51 ++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index c1d252841b..df2f9a7bc1 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -136,3 +136,54 @@ jobs:
       - name: Install dev dependencies and run example tests for GNU/Linux with Python 3.11
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.11
         run: nox -s examples
+
+  # temporary job to test building docs on push, besides building locally
+  build_docs:
+    needs: style
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+
+    steps:
+      - name: Check out PyBaMM repository
+        uses: actions/checkout@v3
+
+      # dot -c is for registering graphviz fonts and plugins
+      - name: Install Linux system dependencies
+        run: |
+          sudo apt-get update
+          sudo dot -c
+          sudo apt-get install gfortran gcc graphviz pandoc libopenblas-dev texlive-full latexmk dvipng
+
+      - name: Set up Python 3.11
+        id: setup-python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+          cache: 'pip'
+          cache-dependency-path: setup.py
+
+      - name: Install PyBaMM dependencies
+        run: |
+          pip install --upgrade pip wheel setuptools nox
+          pip install -e .[all,docs]
+
+      - name: Install SuiteSparse and SUNDIALS on GNU/Linux
+        run: nox -s pybamm-requires
+
+      - name: Install docs dependencies and run doctests for GNU/Linux with Python 3.11
+        run: |
+          nox -s doctests
+          rm -rf docs/build/
+
+      - name: Check if HTML docs can be built
+        run: |
+          sphinx-build -j auto docs docs/build/
+          rm -rf docs/build/
+
+      - name: Check if PDF docs can be built
+        run: |
+          sphinx-build -M latexpdf docs/ docs/build/
+          cd docs/build/latex/
+          make clean
+          latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode

From cf1b276ab44cb08f890e602f495c7719b9c8ccf4 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 23:09:35 +0530
Subject: [PATCH 06/19] Fix undefined module LaTeX warning

---
 docs/source/api/index.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 432461a58e..5c385ee2e5 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -1,5 +1,3 @@
-.. module:: pybamm
-
 .. _api_docs:
 
 #################

From 27a4a560e62089c49cd6ec6bca9b2dfaa2233473 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 23:11:37 +0530
Subject: [PATCH 07/19] Install Linux system dependencies

---
 .github/workflows/test_on_push.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index df2f9a7bc1..ae24c87a61 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -152,7 +152,6 @@ jobs:
       - name: Install Linux system dependencies
         run: |
           sudo apt-get update
-          sudo dot -c
           sudo apt-get install gfortran gcc graphviz pandoc libopenblas-dev texlive-full latexmk dvipng
 
       - name: Set up Python 3.11

From 74cb7cdb16ddddbd82dab594368dfb0c7cf23271 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Wed, 23 Aug 2023 23:34:14 +0530
Subject: [PATCH 08/19] Fix HTML build warnings

---
 .github/workflows/test_on_push.yml | 2 +-
 docs/sphinxext/extend_parent.py    | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index ae24c87a61..9fe1f56afd 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -152,7 +152,7 @@ jobs:
       - name: Install Linux system dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install gfortran gcc graphviz pandoc libopenblas-dev texlive-full latexmk dvipng
+          sudo apt-get install gfortran gcc graphviz pandoc libopenblas-dev texlive-latex-extra latexmk dvipng
 
       - name: Set up Python 3.11
         id: setup-python
diff --git a/docs/sphinxext/extend_parent.py b/docs/sphinxext/extend_parent.py
index 00752e1483..54985109cb 100644
--- a/docs/sphinxext/extend_parent.py
+++ b/docs/sphinxext/extend_parent.py
@@ -21,6 +21,7 @@ def process_docstring(app, what, name, obj, options, lines):
             base_cls_name = f"{getmro(obj)[1].__module__}.{getmro(obj)[1].__name__}"
             # add the extends keyword to the docstring
             lines.append(".. only:: not latex\n")
+            lines.append("\n")
             lines.append(f"    **Extends:** :class:`{base_cls_name}`")
 
 

From f8f3f3eeb88091c0f54394d711410cc6eaf474bc Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 21:17:46 +0530
Subject: [PATCH 09/19] Try custom PDF build job and upload artifact

---
 .github/workflows/test_on_push.yml | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index 9fe1f56afd..532b84eb97 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -183,6 +183,13 @@ jobs:
       - name: Check if PDF docs can be built
         run: |
           sphinx-build -M latexpdf docs/ docs/build/
-          cd docs/build/latex/
-          make clean
-          latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode
+          cd docs/build/
+          rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz PyBaMM.pdf PyBaMM.dvi  *.fls *.fdb_latexmk
+          latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
+          test -f pybamm.pdf && echo "pybamm.pdf exists. Copying source file."
+
+      - name: Upload PDF docs
+        uses: actions/upload-artifact@v2
+        with:
+          name: pybamm-docs
+          path: docs/build/pybamm.pdf

From a5d3da813a631e72668b8848147514ddaef036e8 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 21:35:36 +0530
Subject: [PATCH 10/19] Modify PDF build workflow

---
 .github/workflows/test_on_push.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index 532b84eb97..0094fb3427 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -182,7 +182,7 @@ jobs:
 
       - name: Check if PDF docs can be built
         run: |
-          sphinx-build -M latexpdf docs/ docs/build/
+          sphinx-build -T -E -b latex -D language=en docs docs/build
           cd docs/build/
           rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz PyBaMM.pdf PyBaMM.dvi  *.fls *.fdb_latexmk
           latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true

From bfe7dd489a4248022e8f31566c12d01924854ef1 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 22:38:43 +0530
Subject: [PATCH 11/19] Add custom `post_build` job for PDFs on RTD

---
 .readthedocs.yaml | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index d97966ee38..48a5b24743 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -11,8 +11,9 @@ sphinx:
   configuration: docs/conf.py
   fail_on_warning: false
 
+# PDF builds are disabled here because they are built in a custom fashion
+# by extending the RTD build process, see below
 formats:
-  - pdf
   - epub
   - htmlzip
 
@@ -31,6 +32,19 @@ build:
   jobs:
     post_checkout:
       - git fetch --unshallow
+    # Altered PDF build and upload job, attributed to
+    # https://stackoverflow.com/a/76992101/14001839
+    post_build:
+      - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
+      # Generate LaTeX files in docs/build/ and doctrees in docs/_build/doctrees, skipping notebooks
+      - python -m sphinx -T -E -b latex -d docs/_build/doctrees -D language=en docs docs/build/
+      - cd docs/build/
+      - cat latexmkrc
+      # Map non-zero exit codes to zero
+      - latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
+      # Check if pybamm.pdf exists
+      - test -f pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
+      - cd ../../ && cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
 
 # Optionally declare the Python requirements required to build your docs
 python:

From e3933c05aca77958d31c2ec9fd99b69139505982 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 22:38:57 +0530
Subject: [PATCH 12/19] Revert "Fix undefined module LaTeX warning"

This reverts commit cf1b276ab44cb08f890e602f495c7719b9c8ccf4.
---
 docs/source/api/index.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 5c385ee2e5..432461a58e 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -1,3 +1,5 @@
+.. module:: pybamm
+
 .. _api_docs:
 
 #################

From b5d3cc29e94c3f120c6b5fc3bf796a2fe5a9ae84 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 22:41:29 +0530
Subject: [PATCH 13/19] Revert latex changes for extensions

---
 docs/sphinxext/extend_parent.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/sphinxext/extend_parent.py b/docs/sphinxext/extend_parent.py
index 54985109cb..25978fe804 100644
--- a/docs/sphinxext/extend_parent.py
+++ b/docs/sphinxext/extend_parent.py
@@ -20,9 +20,7 @@ def process_docstring(app, what, name, obj, options, lines):
             # get the base class name
             base_cls_name = f"{getmro(obj)[1].__module__}.{getmro(obj)[1].__name__}"
             # add the extends keyword to the docstring
-            lines.append(".. only:: not latex\n")
-            lines.append("\n")
-            lines.append(f"    **Extends:** :class:`{base_cls_name}`")
+            lines.append(f"**Extends:** :class:`{base_cls_name}`")
 
 
 def setup(app):

From 84a503dfe979826d66aaaa08452b115fbb5256f2 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 22:41:59 +0530
Subject: [PATCH 14/19] Revert "Remove SVG files from LaTeX builds"

This reverts commit 2ec97c14f34f0f39d19e648ec9c99658a43b907a.
---
 docs/index.rst | 103 ++++++++++++++++++++++++-------------------------
 1 file changed, 50 insertions(+), 53 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index b2e0073780..3e5d54ecb5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -38,80 +38,77 @@ Broadly, PyBaMM consists of
 Together, these enable flexible model definitions and fast battery simulations, allowing users to
 explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.
 
-.. SVG images sometimes cause LaTeX build errors
-.. only:: not latex
+.. grid:: 2
 
-   .. grid:: 2
+   .. grid-item-card::
+      :img-top: _static/index-images/getting_started.svg
 
-      .. grid-item-card::
-         :img-top: _static/index-images/getting_started.svg
+      User Guide
+      ^^^^^^^^^^
 
-         User Guide
-         ^^^^^^^^^^
+      The user guide is the best place to start learning PyBaMM. It contains an installation
+      guide, an introduction to the main concepts and links to additional tutorials.
 
-         The user guide is the best place to start learning PyBaMM. It contains an installation
-         guide, an introduction to the main concepts and links to additional tutorials.
+      +++
 
-         +++
+      .. button-ref:: source/user_guide/index
+         :expand:
+         :color: secondary
+         :click-parent:
 
-         .. button-ref:: source/user_guide/index
-            :expand:
-            :color: secondary
-            :click-parent:
+         To the user guide
 
-            To the user guide
+   .. grid-item-card::
+      :img-top: _static/index-images/examples.svg
 
-      .. grid-item-card::
-         :img-top: _static/index-images/examples.svg
+      Examples
+      ^^^^^^^^
 
-         Examples
-         ^^^^^^^^
+      Examples and tutorials can be viewed on the GitHub examples page,
+      which also provides a link to run them online through Google Colab.
 
-         Examples and tutorials can be viewed on the GitHub examples page,
-         which also provides a link to run them online through Google Colab.
+      +++
 
-         +++
+      .. button-ref:: source/examples/index
+         :expand:
+         :color: secondary
+         :click-parent:
 
-         .. button-ref:: source/examples/index
-            :expand:
-            :color: secondary
-            :click-parent:
+         To the examples
 
-            To the examples
+   .. grid-item-card::
+      :img-top: _static/index-images/api.svg
 
-      .. grid-item-card::
-         :img-top: _static/index-images/api.svg
+      API Documentation
+      ^^^^^^^^^^^^^^^^^
 
-         API Documentation
-         ^^^^^^^^^^^^^^^^^
+      The reference guide contains a detailed description of the functions,
+      modules, and objects included in PyBaMM. The reference describes how the
+      methods work and which parameters can be used.
 
-         The reference guide contains a detailed description of the functions,
-         modules, and objects included in PyBaMM. The reference describes how the
-         methods work and which parameters can be used.
+      +++
 
-         +++
+      .. button-ref:: source/api/index
+         :expand:
+         :color: secondary
+         :click-parent:
 
-         .. button-ref:: source/api/index
-            :expand:
-            :color: secondary
-            :click-parent:
+         To the API documentation
 
-            To the API documentation
+   .. grid-item-card::
+      :img-top: _static/index-images/contributor.svg
 
-      .. grid-item-card::
-         :img-top: _static/index-images/contributor.svg
+      Contributor's Guide
+      ^^^^^^^^^^^^^^^^^^^
 
-         Contributor's Guide
-         ^^^^^^^^^^^^^^^^^^^
+      Contributions to PyBaMM and its development are welcome! If you have ideas for
+      features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
 
-         Contributions to PyBaMM and its development are welcome! If you have ideas for
-         features, bug fixes, models, spatial methods, or solvers, we would love to hear from you.
+      +++
 
-         +++
+      .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
+         :expand:
+         :color: secondary
+         :click-parent:
 
-         .. button-link:: https://github.com/pybamm-team/PyBaMM/blob/develop/CONTRIBUTING.md
-            :expand:
-            :color: secondary
-            :click-parent:
-
-            To the contributor's guide
+         To the contributor's guide

From ea5ac0c9aebd8a0e8985a95993662075630d8433 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Mon, 28 Aug 2023 22:48:15 +0530
Subject: [PATCH 15/19] Cleanup unneeded docs build job

---
 .github/workflows/test_on_push.yml | 57 ------------------------------
 1 file changed, 57 deletions(-)

diff --git a/.github/workflows/test_on_push.yml b/.github/workflows/test_on_push.yml
index 0094fb3427..c1d252841b 100644
--- a/.github/workflows/test_on_push.yml
+++ b/.github/workflows/test_on_push.yml
@@ -136,60 +136,3 @@ jobs:
       - name: Install dev dependencies and run example tests for GNU/Linux with Python 3.11
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == 3.11
         run: nox -s examples
-
-  # temporary job to test building docs on push, besides building locally
-  build_docs:
-    needs: style
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-
-    steps:
-      - name: Check out PyBaMM repository
-        uses: actions/checkout@v3
-
-      # dot -c is for registering graphviz fonts and plugins
-      - name: Install Linux system dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install gfortran gcc graphviz pandoc libopenblas-dev texlive-latex-extra latexmk dvipng
-
-      - name: Set up Python 3.11
-        id: setup-python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.11
-          cache: 'pip'
-          cache-dependency-path: setup.py
-
-      - name: Install PyBaMM dependencies
-        run: |
-          pip install --upgrade pip wheel setuptools nox
-          pip install -e .[all,docs]
-
-      - name: Install SuiteSparse and SUNDIALS on GNU/Linux
-        run: nox -s pybamm-requires
-
-      - name: Install docs dependencies and run doctests for GNU/Linux with Python 3.11
-        run: |
-          nox -s doctests
-          rm -rf docs/build/
-
-      - name: Check if HTML docs can be built
-        run: |
-          sphinx-build -j auto docs docs/build/
-          rm -rf docs/build/
-
-      - name: Check if PDF docs can be built
-        run: |
-          sphinx-build -T -E -b latex -D language=en docs docs/build
-          cd docs/build/
-          rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ps *.tar *.tar.gz *.tar.bz2 *.tar.xz PyBaMM.pdf PyBaMM.dvi  *.fls *.fdb_latexmk
-          latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
-          test -f pybamm.pdf && echo "pybamm.pdf exists. Copying source file."
-
-      - name: Upload PDF docs
-        uses: actions/upload-artifact@v2
-        with:
-          name: pybamm-docs
-          path: docs/build/pybamm.pdf

From 737924337b3fda55e4fc356c25d728bbdc16dd0c Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Tue, 29 Aug 2023 14:18:04 +0530
Subject: [PATCH 16/19] Debug file locations

---
 .readthedocs.yaml | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 48a5b24743..bf5fe91119 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -35,16 +35,25 @@ build:
     # Altered PDF build and upload job, attributed to
     # https://stackoverflow.com/a/76992101/14001839
     post_build:
+      - pwd
       - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
       # Generate LaTeX files in docs/build/ and doctrees in docs/_build/doctrees, skipping notebooks
       - python -m sphinx -T -E -b latex -d docs/_build/doctrees -D language=en docs docs/build/
+      - pwd
       - cd docs/build/
+      - ls
       - cat latexmkrc
+      - pwd
       # Map non-zero exit codes to zero
       - latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
+      - pwd
       # Check if pybamm.pdf exists
+      - pwd
       - test -f pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
+      - pwd
       - cd ../../ && cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
+      - pwd
+      - ls $READTHEDOCS_OUTPUT/pdf/
 
 # Optionally declare the Python requirements required to build your docs
 python:

From c26fc9fb0e249d76ff5137a64c858913b4829ddc Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Tue, 29 Aug 2023 14:30:40 +0530
Subject: [PATCH 17/19] More debug

---
 .readthedocs.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index bf5fe91119..3b6acdb947 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -36,13 +36,13 @@ build:
     # https://stackoverflow.com/a/76992101/14001839
     post_build:
       - pwd
+      - ls
       - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
       # Generate LaTeX files in docs/build/ and doctrees in docs/_build/doctrees, skipping notebooks
       - python -m sphinx -T -E -b latex -d docs/_build/doctrees -D language=en docs docs/build/
       - pwd
-      - cd docs/build/
       - ls
-      - cat latexmkrc
+      - cd docs/build/ && cat latexmkrc
       - pwd
       # Map non-zero exit codes to zero
       - latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true

From 279cf4af452e5670956f269bce7f2f4601137ba3 Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Tue, 29 Aug 2023 15:02:51 +0530
Subject: [PATCH 18/19] Further debug and copy source files

---
 .readthedocs.yaml | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 3b6acdb947..4fafb6e7aa 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -30,29 +30,22 @@ build:
     # rust: "1.64"
     # golang: "1.19"
   jobs:
+    # Unshallow the git clone otherwise this may cause issues with Sphinx extensions
     post_checkout:
       - git fetch --unshallow
     # Altered PDF build and upload job, attributed to
     # https://stackoverflow.com/a/76992101/14001839
     post_build:
-      - pwd
-      - ls
       - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
       # Generate LaTeX files in docs/build/ and doctrees in docs/_build/doctrees, skipping notebooks
       - python -m sphinx -T -E -b latex -d docs/_build/doctrees -D language=en docs docs/build/
-      - pwd
-      - ls
       - cd docs/build/ && cat latexmkrc
-      - pwd
       # Map non-zero exit codes to zero
-      - latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
-      - pwd
+      - cd docs/build/ && latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
       # Check if pybamm.pdf exists
-      - pwd
-      - test -f pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
-      - pwd
-      - cd ../../ && cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
-      - pwd
+      - test -f docs/build/pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
+      - ls $READTHEDOCS_OUTPUT/pdf/
+      - cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
       - ls $READTHEDOCS_OUTPUT/pdf/
 
 # Optionally declare the Python requirements required to build your docs

From f5004e6e6257df703808d134b4300b8094b1899a Mon Sep 17 00:00:00 2001
From: Agriya Khetarpal <74401230+agriyakhetarpal@users.noreply.github.com>
Date: Tue, 29 Aug 2023 15:47:24 +0530
Subject: [PATCH 19/19] Cleanup PDF build job on Read the Docs

---
 .readthedocs.yaml | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 4fafb6e7aa..f907ac23d5 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -35,6 +35,7 @@ build:
       - git fetch --unshallow
     # Altered PDF build and upload job, attributed to
     # https://stackoverflow.com/a/76992101/14001839
+    # This also runs on PR builds, but does not upload the PDF
     post_build:
       - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
       # Generate LaTeX files in docs/build/ and doctrees in docs/_build/doctrees, skipping notebooks
@@ -42,11 +43,8 @@ build:
       - cd docs/build/ && cat latexmkrc
       # Map non-zero exit codes to zero
       - cd docs/build/ && latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
-      # Check if pybamm.pdf exists
       - test -f docs/build/pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
-      - ls $READTHEDOCS_OUTPUT/pdf/
       - cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
-      - ls $READTHEDOCS_OUTPUT/pdf/
 
 # Optionally declare the Python requirements required to build your docs
 python: