gh-139257: escape enumerator-like letters to support docutils 0.22

[stefanor]

Escape things that look like Roman numerals. Docutils 0.22 includes a new roman-numeral interpreter that falls over some of our content. Escape anything that causes trouble.

Python itself isn't using docutils 0.22 yet for its doc generation, but some Linux distributions have updated to it.

An alternative to GH-139258

• Issue: Documentation doesn't generate with docutils >= 0.22 #139257

---

📚 Documentation preview 📚: https://cpython-previews--140031.org.readthedocs.build/

[picnixz]

Well, if this change is actually sufficient it's good. But that means that we need to be careful when adding roman-like text. What I find annoying is the Q/A modifications, but I don't know how we could do otherwise.

[AA-Turner]

This feels like a Docutils bug if it requires this much escaping?

A

[picnixz]

This feels like a Docutils bug if it requires this much escaping?

That's because we have no way of disabling roman numeral handling in docutils >= 0.22, unless we specify compatible enumerator-like objects (that are implementation details in docutils and only in >= 0.22). See the issue for the commit that changed this.

[picnixz]

Note: what would be ideal is for docutils to check first the return value of a converter, and if it is None, then assume that the conversion is disabled. That would be the cleanest way to do it (and our monkey patch would be compatible with older docutils versions)

[stefanor]

This feels like a Docutils bug if it requires this much escaping?

Presumably that's what @birkenfeld thought when implementing the monkey-patch in #48813.

The alternative here is to re-instate #139258 and update the monkey-patch.

[stefanor]

I added a second commit to remove the monkey-patch entirely. But instead of doing that, we could make it raise an explicit exception, to avoid accidentally introducing Roman-numbered lists.

[hugovk]

What I find annoying is the Q/A modifications, but I don't know how we could do otherwise.

Other FAQs use headings for the questions, which also makes them linkable:

• https://docs.python.org/3/faq/design.html#why-does-python-use-indentation-for-grouping-of-statements
• https://docs.python.org/3/faq/extending.html#how-do-i-catch-the-output-from-pyerr-print-or-anything-that-prints-to-stdout-stderr

[picnixz]

Other FAQs use headings for the questions, which also makes them linkable:

That would indeed be better. I think we have two distinct issues:

• Transform Q/A into headers (independent of docutils support, this is indeed better and more helpful for users and for us if we want to link them).
• Either patch our current docs to avoid the enumerator conversion, or patch docutils directly so that we can provide a "noop" enumerator.

[stefanor]

But instead of doing that, we could make it raise an explicit exception, to avoid accidentally introducing Roman-numbered lists.

Changed to that.

Also, added a couple of additional commits for other docutils 0.22 issues.

[hugovk]

See PR #142056 for an alternative.