PDF generation failed due to LATEXOPTS leading to a build fail

[gwilku]

Details

• Read the Docs project URL: https://readthedocs.org/projects/jscan-docs/
• Build URL (if applicable): https://readthedocs.org/projects/jscan-docs/builds/19778742/
• Latest working Build: March 9, 2023 https://readthedocs.org/projects/jscan-docs/builds/19727711/

Expected Result

Documentation should be built as usual, as the only fix was adding a small change to the contents.

Actual Result

Instead I am getting an error about PDF not being generated due to some issues with LATEXOPTS.

Build failed
Error
PDF generation failed. The build log below contains information on what errors caused the failure.Our code has recently changed to fail the entire build on PDF errors, where we used to pass the build when a PDF was created.Please contact us if you need help understanding this error.

The details don't point to any specific place or file in my documenation. As a workaround I disabled PDF generation.

[gwilku]

Solved it - sort of. PDF can't be generated with glyphs like 🚀 or 💡.
Except it works in the official RTD docs... No idea how, but that's a different story. Guess I'll live without either these or PDFs and maybe one day figure out how on earth it works here: https://docs.readthedocs.io/en/stable/guides/

[liuverta]

RTD released a new version this morning (#10146) which included a new change which breaks builds if PDF generation fails (#10113).

[gwilku]

RTD released a new version this morning (#10146) which included a new change which breaks builds if PDF generation fails (#10113).

Well, yes, I am aware of it. I'm looking more for a solution rather than an explanation though...

[seanlaw]

@gwilku Are you able to share what you did to resolve this? I unchecked the "Enable PDF build" and "Enable EPUB build" in the advanced settings but am still seeing the same error.

[ekansa]

Just chiming in that I'd love to have some magic configuration to add that would make PDF generation / LATEXOPTS "gracefully degrade" rather than completely bomb out and fail.

[gwilku]

@seanlaw I fixed my config file (.readthedocs.yml), because it overrides the settings on the website (as advised by the info on top of the settings section, which I blissfully ignored :D )

[Bilokin]

I have the similar build fail, but my error is a bit more clear: I use greek letters in text or formulas, which fail the build.
How can I check the PDF build on my machine?

Also, the workaround doesn't work for me, I cannot disable the PDF generation:
I don't have formats section in the yaml file, the corresponding checkmark on the admin page is disabled and the changes are saved, but the PDF build is still being performed.
Recent build: https://readthedocs.org/projects/syscorrfw/builds/19801519/

[humitos]

@Bilokin

I don't have formats section in the yaml file

It seems you have formats: all in your YAML file: https://stash.desy.de/projects/B2PP/repos/systematic_corrections_framework/browse/.readthedocs.yaml#3

[Bilokin]

@humitos, idk where I was looking at! Thanks!

[humitos]

For those that find this issue while researching about why their builds are failing because of PDF and how to fix them, this comment is for you 😉

Why my builds started failing due to PDF issues on Tuesday 15, March?

Read the Docs deployed a change that makes builds to fail when the commands for PDF generation fail. This is, any of the commands required for PDF generation returns something different than a 0 exit code.

Note that these commands were already failing before Tuesday 15. However, Read the Docs silently ignored them and continue as nothing has happened. The resulting PDF file was broken in some way. It may no showed a font, a whole paragraph, an image, or completely broken.

How I can fix these LaTeX errors?

There are many different situations that could be producing these errors. The best way to solve them is by looking at the errors and reading the Sphinx documentation to tweak LaTeX to be more permissive: https://www.sphinx-doc.org/en/master/latex.html

Unfortunately, there is no a magic solution and LaTeX is not trivial to get it right.

How I can test locally that my PDF is building correctly to speed up the debugging process?

You can pull down a Docker image that has Sphinx (and all its LaTeX dependencies) installed and do your debugging there. Read https://www.sphinx-doc.org/en/master/usage/installation.html#docker to know more about this.

How I can disable the PDF generation to workaround this issue?

Using a .readthedocs.yaml configuration file

You should put formats: none in your configuration file to avoid building the PDF. Read https://docs.readthedocs.io/en/stable/config-file/v2.html#formats for more granularity configuration.

Using the project advanced settings from the UI

Note
This solution does not work if you are using a .readthedocs.yaml config file.

You have to

1. Go to your project on Read the Docs
2. Click on the "Admin" tab
3. Click on "Advanced settings" menu
4. Scroll down to the bottom and uncheck "Enable PDF build"

LaTeX is hard. How do I generate PDFs with a different tool?

You can generate PDF with any tool you feel comfortable with. Then only thing you have to do is to save the resulting PDF file as $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT folder. Read the Docs will grab that file and serve it.

An example using SimplePDF:

# .readthedocs.yaml

build:
  os: "ubuntu-22.04"
  tools:
    python: "3"
  jobs:
    post_build:
      - pip install sphinx-simplepdf
      - sphinx-build -M simplepdf docs/ /tmp
      - mv /tmp/simplepdf/"Test Builds.pdf" $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf

There is a live example of something similar at https://test-builds.readthedocs.io/en/all-formats-build-jobs/ in case you want to investigate a little more over a working project. This is the 📚 resulting PDF.

[ericholscher]

Update

Just a heads up, we're rolling back the hard failures on PDF builds for now. We will be re-enabling this configuration in a few weeks, but we wanted to give people a bit more time to react without having their builds be broken.

This is now rolled back -- if anyone could confirm PDF builds are not failing these builds again, I would appreciate it.

[vEpiphyte]

I have done a successful PDF build for my documentation with the rolled back change.

[ekansa]

@ericholscher Thanks! I'm also confirming the happy impact of your rollback. I'll study sphinx-simplepdf in the hope it'll be easier for us than LaTex.

[stsewd]

We reverted the change, so all builds should be passing again.