PDF build fails on projects with multiple latex documents

[cwalther]

Details

• Read the Docs project URL: https://pewpew.readthedocs.io/en/latest/
• Build URL: https://readthedocs.org/projects/pewpew/builds/15077480/
• Read the Docs username: cwalther (although this project is not mine)

Steps to Reproduce

Have a conf.py that specifies multiple latex_documents, such as in the project above, or mentioned in https://stackoverflow.com/questions/60749429/can-i-build-multiple-pdfs-from-the-same-source-in-readthedocs:

latex_documents = [
    (master_doc, 'PewPew.tex', u'PewPew Documentation',
     u'Radomir Dopieralski', 'manual'),
    ('handout/index', 'Handout.tex', 'Handout', 'Christian Walther', 'howto'),
]

Expected Result

• Acceptable: Build succeeds, first document (PewPew.pdf) is published, further documents (Handout.pdf) are discarded.
• Preferred: Build succeeds, all documents are published.

Actual Result

Build fails with

Latexmk: Need to specify at most one filename if jobname specified, 
    but 2 were found (after defaults and wildcarding).
Use
   latexmk -help
to get usage information

This appears to be because Read the Docs calls latexmk by itself without passing a .tex file name instead of using _build/latex/Makefile which would do it correctly:

readthedocs.org/readthedocs/doc_builder/backends/sphinx.py

Line 510 in 458ed61

def _build_latexmk(self, cwd, latex_cwd):

Using the Makefile was discussed in #4454 but dismissed for reasons that are not entirely clear to me.

[humitos]

Hi! I think this is a duplicate of #2045. We currently don't support multiple PDF output. However, we are considering this use case in our new builders (see https://github.com/readthedocs/readthedocs.org/pull/8190/files#r638919502). We are still discussing its implementation and we don't have an ETA yet, unfortunately.

Please, subscribe to #2045 to receive news about the progress on multiple PDF output files.

[cwalther]

Not really a duplicate in my opinion – this one is primarily about the build failure (which apparently didn’t occur yet in 2016 when #2045 was filed, probably because the latexmk path didn’t exist yet and the pdflatex path was used instead, which appears to do this correctly), while #2045 is about the ability to publish all the documents instead of just the first one, which for me, as mentioned, would be nice but not absolutely required.

But I’m fine with continuing the discussion in #2045.

[humitos]

while #2045 is about the ability to publish all the documents instead of just the first one, which for me, as mentioned, would be nice but not absolutely required.

IMO, publishing just the first PDF documentation without failing the build would be unexpected behavior for many users as well. If the users is defining multiple PDF output, they would expect them all as output, and if we are not building/serving them, I'm fine failing the build to communicate this to users. The error message that Read the Docs presents to the user could be better, tho 😄

[cwalther]

OK, good point. Thinking about it more thoroughly, what I’m objecting to is actually not marking the build as failed, but the failure to build and publish the main PDF.

Right now we have:

• HTML is published, main PDF is not published, additional PDF is not published, build is marked as failed.

What I would consider acceptable would be:

• HTML is published, main PDF is published, additional PDF is not published, build is marked as failed.

In other words, treating PDF the same as HTML. Assuming that HTML being published despite the failed build is intentional.

But I don’t insist on it, I will just extend my conf.py to exclude the additional documents when building on RTD.

[humitos]

Assuming that HTML being published despite the failed build is intentional.

This is interesting. IMO, we shouldn't publish the HTML if the build fails. However, I know we have discussed this in the past but I don't remember where we landed or where that discussion is. @ericholscher do you remember the reasons?

[ericholscher]

@humitos Because HTML was being uploaded directly after it was built to increase the speed of publishing. I thought we'd reverted this, but if we haven't we should. I agree it shouldn't publish if the build doesn't pass.

There is also the issue of the PDF builds failing even while producing valid output, but that's a different issue.