Using Sphinx 3's C domain syntax

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

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

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

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

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

A

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.

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

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

2 Likes