Where should the Argument Clinic docs live?

Currently, the Argument Clinic docs live in the How-To section of docs.python.org:

Argument Clinic How-To — Python 3.11.4 documentation.

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.

What do y’all think?


I would like to give a +1 about writing general guide about AC. One question, we don’t have to care about version changed issue of AC right?

FTR, I proposing to move the existing AC guide from the Python docs to the devguide :slight_smile:

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.

1 Like

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.

1 Like

But I still feel the need for a general guide on using AC in the dev guide.
It’s another layer…

1 Like

Yes, we definitely need an introduction to Argument Clinic in the devguide. There’s already an issue about this:

1 Like

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

1 Like

Just to comment on this point—

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.

1 Like

Thanks, CAM, that’s good to know!

1 Like

So far, I’ve only received encouraging reactions to this. I’m going to prepare the move later this week, and unless a big objection appears, go ahead with the move hopefully next week.

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.)

1 Like