Restore building of documentation downloads

[EliahKagan]

Although documentation resumed being built in 634151a, and the RTD theme and API Reference section were restored in 64ad585 (#1843), documentation for download did not resume being built, with 3.1.37 (not 3.1.42) being the latest version listed at:

• https://readthedocs.org/projects/gitpython/downloads/

Three kinds of downloadable documentation are supported -- PDF, ePub, and HTML -- and all three were previously being built but all have stopped.

This attempts to resume building all three, listing all under the formats key in .readthedocs.yml. all currently should have the same effect as listing all of htmlzip, pdf, and epub, per:

• https://docs.readthedocs.io/en/stable/downloadable-documentation.html
• https://docs.readthedocs.io/en/stable/config-file/v2.html#formats

---

As I understand it, for purposes of efficiency, pull request preview builds do not build that documentation. The Limitations of such builds include:

Additional formats like PDF and EPUB aren’t built, to reduce build time.

So the effect, even if successful, may not be observable immediately.

[Byron]

Thanks a lot for your tremendous help with this!

I took a look and found the build in question: https://readthedocs.org/projects/gitpython/builds/23623575/ .

Unfortunately, it seems to reject the configuration entirely which I think may also be the case outside of the PR based build.

If you want, I can merge and we see what happens in main, but if docs still fail to build the commit will probably have to be undone.

Please let me know what to do next.
Thank you

[EliahKagan]

This was my mistake: the value of formats needs either to be a sequence of strings naming specific documentation types, or the string all. But I had made it a length-1 sequence whose element was the string all.

I've amended to fix that and also fix the claim in the commit message about how the value works (I thought of adding another commit, but I was rebasing onto main anyway).

The build seems to pass now:
https://readthedocs.org/projects/gitpython/builds/23625406/

[Byron]

Ah, great, that works, thanks a lot!

I think with the next release we can validate that downloads are indeed back.

[EliahKagan]

I think with the next release we can validate that downloads are indeed back.

The download page already has them for the "latest" documentation, since this PR was merged. The "latest" documentation downloads (like other "latest" documentation on Read the Docs) builds from the main branch.

I can tell it is really building from commits more recent than the most recent release because, for example, the PDF has a section on "Top-Level" in its API Reference, which was introduced in #1855.

Downloadable documentation is not built in pull request preview builds--at least not in formats other than HTML, and I haven't seen "HTMLZip" for PR builds either. But it is built otherwise, both for tags and for the main branch.

More broadly, I do agree that all notable reconfiguration of Read the Docs should still be checked to see how it is working after the next release.

[Byron]

That's amazing!

I can tell it is really building from commits more recent than the most recent release because, for example, the PDF has a section on "Top-Level" in its API Reference, which was introduced in #1855.

And the PDF looks really good as well, it's like a book with more than 160 pages! Quite astonishing.

More broadly, I do agree that all notable reconfiguration of Read the Docs should still be checked to see how it is working after the next release.

I'd definitely be surprised if it wouldn't be working for a release, and consider myself tentatively optimistic :).