[Django] #34756: Docs build failure when using Sphinx 7.1.1
Django
-------------------------------------+-------------------------------------
Reporter: Natalia | Owner: Natalia Bidart
Bidart |
Type: | Status: assigned
Cleanup/optimization |
Component: | Version: 4.2
Documentation |
Severity: Normal | Keywords:
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
While preparing the release of Django 4.2.4, I built the docs in the
`main` and `stable/4.2.x` branches and in both I got this error (Sphinx
7.1.1. was released 5 days ago):
{{{
(djangodev) [nessita@socrates 0 ~/fellowship/django/docs main|⚑ 1]$ make
html
sphinx-build -b djangohtml -n -d _build/doctrees -D language=en .
_build/html
Running Sphinx v7.1.1
making output directory... done
loading intersphinx inventory from
https://docs.python.org/3/objects.inv...
loading intersphinx inventory from https://www.sphinx-
doc.org/en/master/objects.inv...
loading intersphinx inventory from
https://www.psycopg.org/psycopg3/docs/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output...
building [djangohtml]: targets for 567 source files that are out of date
updating environment: [new config] 567 added, 0 changed, 0 removed
reading sources... [100%] topics/testing/tools
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [ 2%] howto/custom-file-storage
Exception occurred:
File "/home/nessita/.virtualenvs/djangodev/lib/python3.11/site-
packages/sphinx/writers/html5.py", line 206, in visit_desc_parameter
on_separate_line = self.multi_line_parameter_list
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'DjangoHTMLTranslator' object has no attribute
'multi_line_parameter_list'
The full traceback has been saved in /tmp/sphinx-err-2385y4w7.log, if you
want to report the issue to the developers.
Please also report this if it was a user error, so that a better error
message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-
doc/sphinx/issues>. Thanks!
make: *** [Makefile:59: html] Error 2
}}}
I then downgraded Sphinx to `7.0.1` and the built succeeded. I will debug
further after the release, I want to confirm if this is something in our
code or if there is an issue that should be reported to Sphinx upstream.
Nevertheless, I'm creating this ticket to keep track of the error and
resolution.
--
Ticket URL: <https://code.djangoproject.com/ticket/34756>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Bidart
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 4.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
Comment:
Thanks for the report. We can backport fix to all supported branches
(`3.2.x`, `4.1.x`, and `4.2.x`).
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:1>
Django
-------------------------------------+-------------------------------------
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 4.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: Natalia Bidart => David Smith
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 4.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:3>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 4.2
Severity: Normal | Resolution:
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Component: Documentation | Version: 4.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"b3e0170ab546a96930ce3114b0a1a560953c0ff4" b3e0170a]:
{{{
#!CommitTicketReference repository=""
revision="b3e0170ab546a96930ce3114b0a1a560953c0ff4"
Fixed #34756 -- Fixed docs HTML build on Sphinx 7.1+.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Cleanup/optimization | Status: closed
Component: Documentation | Version: 4.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"951dcbb2e6c4d1686706f86c955509ac0ced788c" 951dcbb]:
{{{
#!CommitTicketReference repository=""
revision="951dcbb2e6c4d1686706f86c955509ac0ced788c"
[4.2.x] Fixed #34756 -- Fixed docs HTML build on Sphinx 7.1+.
Backport of b3e0170ab546a96930ce3114b0a1a560953c0ff4 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Cleanup/optimization | Status: closed
Component: Documentation | Version: 4.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"39c9aa1d85c678451b867004c7d797a6f9313224" 39c9aa1]:
{{{
#!CommitTicketReference repository=""
revision="39c9aa1d85c678451b867004c7d797a6f9313224"
[4.1.x] Fixed #34756 -- Fixed docs HTML build on Sphinx 7.1+.
Backport of b3e0170ab546a96930ce3114b0a1a560953c0ff4 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: David
Type: | Smith
Cleanup/optimization | Status: closed
Component: Documentation | Version: 4.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"75418f8c0e5e8fcfb557bf8e69fc1ccfd64b697d" 75418f8c]:
{{{
#!CommitTicketReference repository=""
revision="75418f8c0e5e8fcfb557bf8e69fc1ccfd64b697d"
[3.2.x] Fixed #34756 -- Fixed docs HTML build on Sphinx 7.1+.
Backport of b3e0170ab546a96930ce3114b0a1a560953c0ff4 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34756#comment:8>