gh-136209: Add .. c:var:: declarations for C exception types

[encukou]

• Add .. c:var:: declarations for C exception types. (This needs the type, and adds stable ABI declarations.)
• Convert to list-table to avoid overlong lines
• Merge the 3 tables -- these objects aren't very distinct
• Remove the note about what's a base class. (This wasn't kept to date, and it isn't very useful info. Exceptions can grow subclasses in future Python versions anyway.)
• Name the notes for more clarity
• Remove properly documented names from nitpick_ignore

• Issue: No Sphinx markup for PyExc_* #136209

---

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

[vstinner]

LGTM

[serhiy-storchaka]

I tried to do this before, but gave up when I saw that it was impossible to get rid of PyObject * until we can use :no-typesetting: in Sphinx 7.2. And now it generates also recurring "Part of the Stable ABI" which increases the table height.

[serhiy-storchaka]

Is it possible to add space between three tables? Each table has certain order. When they are merged, there is no order.

[hugovk]

until we can use :no-typesetting: in Sphinx 7.2.

We now can! We're using Sphinx 8.2 for 3.12+ (and 7.2 for 3.11):

cpython/Doc/requirements.txt

Line 10 in c45da6a

sphinx~=8.2.0

[encukou]

:no-typesetting: inflates the source table height.
I personally prefer the “real”-looking definitions with PyObject * and stable ABI notes. To me, these are primarily link targets that you jump to from a search. Who'll scroll up to read the introduction?

But, I'm OK with this :no-typesetting: version too.

Is it possible to add space between three tables? Each table has certain order. When they are merged, there is no order.

I think it's only possible with three separate tables, with misaligned columns.
Do you like this better?

[vstinner]

LGTM. I like the 3 tables. It's closer to the documentation of Python exceptions: https://docs.python.org/dev/library/exceptions.html (grouped by categories, as C API exceptions now).

I have no opinion on :no-typesetting:.

[vstinner]

Maybe here is a better place for .. _standardwarningcategories:, no?

[serhiy-storchaka]

Thank you for your update.

I have no strong preference about the look of the definitions. Stable ABI notes has their value, although they are repetitive and take much space. We could add notes or a special column for the stable ABI version, but this will make the sources even larger. So I left this on you and other reviewers.

Three tables with separate subsection names look much better to me. If you want to align column widths, there is a ways to specify column widths explicitly.

[encukou]

I'll go with the “full” info for this PR, then. It can be slimmed down in the future.
An issue is that the Stable ABI notes are autogenerated (so that documentarians don't need to care about them); moving them elsewhere would mean maintaining them manually.

For future reference, I'm attaching screenshots of both variants, and a little script I used to add the :no-typesetting: everywhere, so anyone can easily experiment :)

With “real” definitions -- bigger but more complete:

With :no-typesetting: and :c:var: -- leaner:

Script to add :no-typesetting:

filename = 'Doc/c-api/exceptions.rst' DEFINITION_START = ' * * .. c:var:: PyObject *' with open(filename) as f: lines = list(f) new_lines = [] for line in lines: new_lines.append(line) if line.startswith(DEFINITION_START): name = line.removeprefix(DEFINITION_START) new_lines.append(' :no-typesetting:\n') new_lines.append('\n') new_lines.append(f' :c:var:`!{name.strip()}`\n') with open(filename, 'w') as f: f.writelines(new_lines)