PDF documentation build broken

[AndrewN]

​https://readthedocs.org/projects/django/builds/ shows that PDF builds of the docs are failing.

The error message in a log from a recent build:

  File "/home/docs/checkouts/readthedocs.org/user_builds/django/checkouts/latest/django/__init__.py", line 1, in <module>
    from django.utils.version import get_version
  File "/home/docs/checkouts/readthedocs.org/user_builds/django/checkouts/latest/django/utils/version.py", line 73, in <module>
    @functools.lru_cache
  File "/home/docs/checkouts/readthedocs.org/user_builds/django/envs/latest/lib/python3.7/functools.py", line 490, in lru_cache
    raise TypeError('Expected maxsize to be an integer or None')
TypeError: Expected maxsize to be an integer or None

The ​last generated PDF has a date of September 27 and on that date in 5bac1719a2fcb “Refs #32355 -- Used @functools.lru_cache as a straight decorator”, lru_cache() was changed to lru_cache on that line.

I believe the issue is that readthedocs is currently using a too-old version of python for the documentation build.

[AndrewN]

PR: ​https://github.com/django/django/pull/15039

[Mariusz Felisiak]

Is seems that "Read The Docs" uses quite old Sphinx 1.8.5 by default, we should install at least ​3.1.0 to get support for Python 3.8. See ​logs.

[GitHub <noreply@…>]

In 447b6c86:

Refs #33247 -- Corrected configuration for Read The Docs.

This pins Sphinx version, because the default Sphinx version used by
RTD is not compatible with Python 3.8+.

This also, sets Python 3.8 for RTD builds which is compatible with all
current versions of Django.

Thanks to Mariusz Felisiak for the suggestion.

[Mariusz Felisiak]

In ​0da7a2e9dab81b622a2000536c6a96de7f46e237

Fixed #33247 -- Added configuration for Read The Docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In df452a22:

[4.0.x] Fixed #33247 -- Added configuration for Read The Docs.

Co-authored-by: Andrew Neitsch <andrew@…>

Backport of 0da7a2e9dab81b622a2000536c6a96de7f46e237 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 2877d264:

[4.0.x] Refs #33247 -- Corrected configuration for Read The Docs.

This pins Sphinx version, because the default Sphinx version used by
RTD is not compatible with Python 3.8+.

This also, sets Python 3.8 for RTD builds which is compatible with all
current versions of Django.

Thanks to Mariusz Felisiak for the suggestion.
Backport of 447b6c866f0741bb68c92dc925a65fb15bfe7995 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 327dac6e:

[3.2.x] Fixed #33247 -- Added configuration for Read The Docs.

Co-authored-by: Andrew Neitsch <andrew@…>

Backport of 0da7a2e9dab81b622a2000536c6a96de7f46e237 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9d171643:

[3.2.x] Refs #33247 -- Corrected configuration for Read The Docs.

This pins Sphinx version, because the default Sphinx version used by
RTD is not compatible with Python 3.8+.

This also, sets Python 3.8 for RTD builds which is compatible with all
current versions of Django.

Thanks to Mariusz Felisiak for the suggestion.

Backport of 447b6c866f0741bb68c92dc925a65fb15bfe7995 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 029c830b:

[2.2.x] Fixed #33247 -- Added configuration for Read The Docs.

Co-authored-by: Andrew Neitsch <andrew@…>

Backport of 0da7a2e9dab81b622a2000536c6a96de7f46e237 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9a4a2b20:

[2.2.x] Refs #33247 -- Corrected configuration for Read The Docs.

This pins Sphinx version, because the default Sphinx version used by
RTD is not compatible with Python 3.8+.

This also, sets Python 3.8 for RTD builds which is compatible with all
current versions of Django.

Thanks to Mariusz Felisiak for the suggestion.

Backport of 447b6c866f0741bb68c92dc925a65fb15bfe7995 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 95a4db3:

Refs #33247 -- Fixed rendering of Unicode chars and emojis in PDF docs build.

[GitHub <noreply@…>]

In adb4100e:

Refs #33247 -- Used XeLaTeX for PDF docs build.