diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d97966ee38..f907ac23d5 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 @@ -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: 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'). # 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} ---