Merge pull request #3292 from agriyakhetarpal/docs-pdf-fix-new

Invoke custom `build.jobs` for PDF builds on Read the Docs

.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
 
@@ -29,8 +30,21 @@ 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
+    # 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
+      - 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
+      - cd docs/build/ && latexmk -r latexmkrc -pdf -f -dvi- -ps- -jobname=pybamm -interaction=nonstopmode || true
+      - test -f docs/build/pybamm.pdf && echo "pybamm.pdf exists. Copying source file to $READTHEDOCS_OUTPUT/pdf/."
+      - cp "docs/build/pybamm.pdf" $READTHEDOCS_OUTPUT/pdf/
 
 # Optionally declare the Python requirements required to build your docs
 python:

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').
     #

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}
 ---