Using Sphinx 3's C domain syntax

Documentation
1

Opening this discussion per @encukou from GH-93738.

Synopsis

CPython recently updated all active bugfix branches to require Sphinx 3.2. This allows using the C domain syntax introduced in Sphinx 3 (docs).

I propose updating the CPython docs to use this new syntax

Background

Sphinx would additionally like to remove support for the pre-v3 syntax, and Python is the only large project using it. (The Linux kernel has migrated to the new syntax.)

The parsing in the new C domain is a lot stricter, meaning that e.g. :c:type:`const char*` is no longer valid.

I proposed this migration on the issue tracker and there seemed to be general consensus, this message is for promulgation to a wider audience.

Please let me know any thoughts or objections to the proposed change. My remaining questions are roughly:

  • Is this change welcome?
  • Does anybody have other concerns?

A

5 Likes
2

FWIW, the main change is that :c:type:, :c:func:, etc. need exact type/function names, and anything more complicated needs to be :c:expr:, for example:

:c:expr:`PyObject*`
:c:expr:`const PyBytesObject*`
:c:expr:`Py_CLEAR(obj)`

Spinx will parse the expression, add syntax highlighting, and – importantly – linkify names (PyObject and Py_CLEAR above).

The disadvantage is losing support for Sphinx 2. IMO, that’s reasonable at this point.

3 Likes
3

For explicitness, we’ve already lost (declared) support for Sphinx 2 per GH-93337 (I should have put a link to this PR in my original post, sorry.)

A

4

The proposal is to backport this to 3.11 and 3.10, right?

5

Yes, to allow future backports without conflicts (Victor and Serhiy agreed).

A

6

I’m assuming Sphinx will give an error if you use :c:type:/:c:func: for expressions, right?
I think it might take a bit for people to adjust to the change, so it’s important that the (now) wrong markup gets recognized quickly by Sphinx, possibly pointing to the correct markup (e.g. :c:expr:). Are you aware of any cases that fail silently and/or produce the wrong result? Should sphinx-lint be updated to catch any of those?

Given the scope of the change, do you think the commit(s) should be added to .git-blame-ignore-revs? If you do, it’s probably easier to just have a few big commits rather than many small ones (e.g. one per file). (Having few commits might be better regardless IMHO).

The devguide will also need to be updated.

7

It fails, yes (a warning is emitted that then fails the build as we pass -W).

Not personally, no.

From one perspective it is large but from another it isn’t – Victor linked GH-84385 which contains many similar sized changes – if I break up into one PR per commit as Petr originally suggested it would be even smaller diff sizes.

A

2 Likes
8

I’m +1 to going ahead with this. I can review+merge each of the PRs needed for this.

3 Likes
9

I’ve opened PRs to implement this (one-ish per commit in my original branch, as Petr suggested)–all are now listed in the introduction to GH-93738.

A

4 Likes