Opened 5 weeks ago

Closed 4 weeks ago

Last modified 4 weeks ago

#36535 closed Bug (fixed)

Ensure compatibility with docutils 0.19 through 0.22+ in admindocs

Reported by: Natalia Bidart Owned by: Natalia Bidart
Component: contrib.admindocs Version: 5.2
Severity: Release blocker Keywords: parse_rst docutils
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (8)

comment:1 by Sarah Boyce, 5 weeks ago

Triage Stage: UnreviewedAccepted

Thank you, confirmed we have test failures with docutils < 0.22
As discussed on the 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

comment:2 by Sarah Boyce, 5 weeks ago

Triage Stage: AcceptedReady for checkin

comment:3 by Sarah Boyce, 5 weeks ago

Triage Stage: Ready for checkinAccepted

comment:4 by Sarah Boyce, 4 weeks ago

Triage Stage: AcceptedReady for checkin

comment:5 by nessita <124304+nessita@…>, 4 weeks ago

Resolution: fixed
Status: assignedclosed

In 9cec8d9f:

Fixed #36535 -- Ensured compatibility with docutils 0.19 through 0.22.

Regression in 65ab92f6a83644bbb555d0eff3a02d8d9301aba4.

comment:6 by Natalia <124304+nessita@…>, 4 weeks ago

In f01ceae:

[5.2.x] Fixed #36535 -- Ensured compatibility with docutils 0.19 through 0.22.

Regression in 65ab92f6a83644bbb555d0eff3a02d8d9301aba4.

Backport of 9cec8d9f55d90fbc162fde23d6ea7a34e322fcae from main.

comment:7 by nessita <124304+nessita@…>, 4 weeks ago

In 9d9b3bc:

[5.1.x] Refs #36535 -- Doc'd that docutils < 0.22 is required.

comment:8 by Natalia <124304+nessita@…>, 4 weeks ago

In 7335a1a9:

[4.2.x] Refs #36535 -- Doc'd that docutils < 0.22 is required.

Backport of 9d9b3bc71702e4bd4b7f8e1602d83fd69f871e94 from stable/5.1.x.

Note: See TracTickets for help on using tickets.
Back to Top