METH_* and Py_TPFLAGS* constants are documented as Python data

[encukou]

For example, a search for Py_TPFLAGS says it's all “Python data”:

Same with METH_.

I guess this should be changed to c:macro:. It doesn't change URLs, but it would break references and Intersphinx links in third-party docs.
And there's a lot of references to these items that use :const: rather than :c:macro:. All of them would need to change, possibly causing conflicts in backports.

---

An additional issue is flag combinations in structures.rst:

.. data:: METH_VARARGS

   This is the typical calling convention, where[...]


.. data:: METH_VARARGS | METH_KEYWORDS

   Methods with these flags must [...]

---

These should look like items of the same category to the reader, but one is a valid c:macro and the other isn't.

Sphinx experts, any tips on how (and whether) to best fix this?

[CAM-Gerlach]

Sphinx experts, any tips on how (and whether) to best fix this?

@AA-Turner is one of the most knowledgeable people on these changes, since he was the one to propose a related set of them in #93738 that have similar effects. This ultimately seems to be more of a strict defect in the CPython docs source than that, though, as the objects are currently not categorized correctly.

As mentioned during the meeting, external links should still work, as the anchors should still be the same. Internal references will need to be updated, and unfortunately I'm not aware of any obvious mechanism to redirect old references (particularly for Intersphinx users, since internal uses can fairly easily update)— @AA-Turner , is there any chance of something like that? However, as long as they are using -n in their builds as they should be, it will let them know exactly what and where they need to update, and it will be a one-time change to fix what would otherwise be an enduring and potentially confusing defect (especially if they are migrated directly to the modern C syntax), so at least to me it seems worthwhile in the long run.

Regarding backporting, not doing so would lead to more conflicts over time and would mean existing docs would not benefit from this defect fix, but on the other hand, not backporting to at least 3.10 would minimize any backward compat concerns (since there are many other changes users expect and need to adapt to between Python docs versions anyway).

[AA-Turner]

There's no way I'm aware of to mitigate this within Sphinx, I think we may just have to bite the bullet and make the changes--best time to plant a tree and all that.

We should though socialise that we are making these changes -- discussion in various documentation fora at the very least.

A

[encukou]

FWIW, a similar issue is: #97908 (Docs for some C struct members repeat the struct name)

[CAM-Gerlach]

FWIW, since this appears it will only break Intersphinx references, it produces a warning (with -n) and will visibly not resolve as a link in the rendered docs, so there will be some visibility already there whenever it happens, without people having to update their docs manually.

[CAM-Gerlach]

To note, in that issue the fragments visible to external links will change, unless we add ref target labels with the old name.

[encukou]

#106919 fixed this, without preserving the URL fragments and external intersphinx references or advertising the changes.
I currently don't have bandwith to do those. If I (or someone else) don't find time by 3.11.0, we'll need to live with it.

[erlend-aasland]

If I (or someone else) don't find time by 3.11.0, we'll need to live with it.

Both 3.11.0 and 3.12.0 have been released; seems we had to live without those advertisements. AFAIK, we did not advertise other similar Sphinx markup corrections. Suggesting to close this.