[Django] #36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia | Owner: Natalia Bidart
Bidart |
Type: Bug | Status: assigned
Component: | Version: 5.2
contrib.admindocs |
Severity: Release | Keywords: parse_rst docutils
blocker |
Triage Stage: | Has patch: 1
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
Docutils 0.22 introduced a breaking-ish change that affects how the
`writer` argument is handled in `docutils.core.publish_parts()`, which is
used in admindocs' `parse_rst()`.

In version 0.22 and above, the `writer` argument can be an instance *or* a
string. Earlier versions (0.19 through 0.21) only support passing the
writer name as a string via `writer_name`, *or* passing an instance
directly to `writer`, but not both interchangeably.

An earlier patch (65ab92f6a83644bbb555d0eff3a02d8d9301aba4) was backported
to Django 5.2.x to avoid test failures and runtime errors with docutils
0.22+, since Django does not currently restrict the dependency beyond
requiring version 0.19 or higher. However, that patch introduced a
backward incompatibility with docutils < 0.22, which now fails due to the
changed usage pattern.

To fix this, a version-agnostic approach is proposed: explicitly
instantiate the writer and avoid use of `writer_name`. This ensures
compatibility with all currently supported docutils versions without
needing to bump the minimum required version.
--
Ticket URL: <https://code.djangoproject.com/ticket/36535>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------

Reporter: Natalia Bidart | Owner: Natalia

| Bidart
Type: Bug | Status: assigned

Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution:
Keywords: parse_rst docutils | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

Comment:

Thank you, confirmed we have test failures with docutils < 0.22
As discussed on the [https://github.com/django/django/pull/19684 PR], we
can bump minimum supported version on main to 0.22 as this is the first to
support Python 3.12 (minum supported Python version since #36005). Hence,
it makes sense for this PR to target 5.2
--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:1>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: assigned
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution:

Keywords: parse_rst docutils | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:2>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: assigned
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution:

Keywords: parse_rst docutils | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Ready for checkin => Accepted

--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:3>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: assigned
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution:

Keywords: parse_rst docutils | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:4>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart

Type: Bug | Status: closed
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution: fixed

Keywords: parse_rst docutils | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by nessita <124304+nessita@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"9cec8d9f55d90fbc162fde23d6ea7a34e322fcae" 9cec8d9f]:
{{{#!CommitTicketReference repository=""
revision="9cec8d9f55d90fbc162fde23d6ea7a34e322fcae"
Fixed #36535 -- Ensured compatibility with docutils 0.19 through 0.22.

Regression in 65ab92f6a83644bbb555d0eff3a02d8d9301aba4.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:5>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: closed
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution: fixed
Keywords: parse_rst docutils | 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 Natalia <124304+nessita@…>):

In [changeset:"f01ceae477a71a1c244c332e1b53a9499e484874" f01ceae]:
{{{#!CommitTicketReference repository=""
revision="f01ceae477a71a1c244c332e1b53a9499e484874"
[5.2.x] Fixed #36535 -- Ensured compatibility with docutils 0.19 through
0.22.

Regression in 65ab92f6a83644bbb555d0eff3a02d8d9301aba4.

Backport of 9cec8d9f55d90fbc162fde23d6ea7a34e322fcae from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:6>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: closed
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution: fixed
Keywords: parse_rst docutils | 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 nessita <124304+nessita@…>):

In [changeset:"9d9b3bc71702e4bd4b7f8e1602d83fd69f871e94" 9d9b3bc]:
{{{#!CommitTicketReference repository=""
revision="9d9b3bc71702e4bd4b7f8e1602d83fd69f871e94"
[5.1.x] Refs #36535 -- Doc'd that docutils < 0.22 is required.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:7>

[Django]

#36535: Ensure compatibility with docutils 0.19 through 0.22+ in admindocs
-------------------------------------+-------------------------------------
Reporter: Natalia Bidart | Owner: Natalia
| Bidart
Type: Bug | Status: closed
Component: contrib.admindocs | Version: 5.2
Severity: Release blocker | Resolution: fixed
Keywords: parse_rst docutils | 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 Natalia <124304+nessita@…>):

In [changeset:"7335a1a9138e905aa681169c3b820fed207edfa5" 7335a1a9]:
{{{#!CommitTicketReference repository=""
revision="7335a1a9138e905aa681169c3b820fed207edfa5"
[4.2.x] Refs #36535 -- Doc'd that docutils < 0.22 is required.

Backport of 9d9b3bc71702e4bd4b7f8e1602d83fd69f871e94 from stable/5.1.x.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36535#comment:8>