The devguide does not mention Argument Clinic at all (except in the experts section).
The clinic docs’s primary audience are core developers and contributors, which is also the primary audience of the devguide. I’d like to suggest we move the clinic docs from docs.python.org to devguide.python.org.
FTR, I proposing to move the existing AC guide from the Python docs to the devguide
Do you mean PEP 387? AC is not bound by those backwards compatibility promises. Quote from the AC docs:
Argument Clinic is considered internal-only for CPython. Its use is not supported for files outside CPython, and no guarantees are made regarding backwards compatibility for future versions. In other words: if you maintain an external C extension for CPython, you’re welcome to experiment with Argument Clinic in your own code. But the version of Argument Clinic that ships with the next version of CPython could be totally incompatible and break all your code.
Well, I am talking about difference implementation between each versions. AC does not need to be backported. It means that guide can be slight different per versions. Since docs.python.org provides each version’s guide, it doesnt matter. but AFAIK, devguide is unified version. I am not sure how AC is frequently changed these days, but I just want know your opinion about this issue. Good example might be defining_class that you added.
Aha, I see your point now. This is a good argument for keeping AC docs in the CPython repo, instead of in the devguide repo.
New features are seldomly added to Argument Clinic. I added the unused argument to CConverter in 3.12. Apart from that, only bugfixes and doc updates have been backported. We do not backport the type annotations, but those do not alter the behaviour of the tool.
So far, I’ve got 6 hearts and some very good critical questions from Dong-hee; thanks! I won’t draw any conclusions yet; I’ll wait a week or two still, because I don’t think we should take lightly on shuffling around docs between the CPython and Devguide repos.
Some brainstorming from my side:
Benefits of AC docs in the devguide repo
less CI churn (devguide CI is a lot quicker than CPython CI)
no docs backports
AC audience aligns with the devguide audience
Benefits of AC docs in the CPython repo
more exposure to (or eyes on) the changes
easier to keep the AC docs aligned with new features in AC
Actually, since the CPython docs is included as an intersphinx mapping in the devguide, its exactly as easy to link/cross-reference CPython docs targets in the devguide as in the CPython docs, as all the same syntax will work transparently.
Additionally, in the devguide cross-reference different specific versions of the CPython docs by adding them as separate intersphinx mappings (like we do in the PEPs), e.g. you can have a xref that always points to the latest dev version, the latest stable version, or a specific feature release.
And cross-referencing source files is as easy or easier thanks to the :cpy-file: role Ezio added to the devguide.
Thoughts on where in the devguide the Argument Clinic docs should live? Perhaps Development Workflow is the best place – there’s already a section about how to write extension modules there.
I don’t think Advanced Tools and CPython Internals are fitting; the former is about third-party tools, and the latter is a collection of explanations/background of various internal concepts (bytecode, compiler, GC, etc.)