Move Argument Clinic's documentation to the Developer's Guide

[AA-Turner]

Would close #1151 and resolve #1148

Differences from #1151:

• I've merged the two commits cited in Migrate Argument Clinic docs from CPython to the devguide #1151 (review) so that git log, git blame, etc will properly track the history
• This branch starts from the current HEAD so that the repository won't have a divergent history
• The redirects in conf.py are removed
• Removed the changes to CODEOWNERS (these need updates anyway as the paths are wrong, it should be internals/garbage-collector.rst and development-tools/clinic.rst). This is from @erlend-aasland's note "I think it's better if this PR only focus on the act of migrating clinic.rst"

cc: @erlend-aasland

This PR should be merged with the default merge option to preserve the history (Squash & Merge should not be used!)

A

---

📚 Documentation preview 📚: https://cpython-devguide--1160.org.readthedocs.build/

[erlend-aasland]

Great, thank you so much, Adam!

[ned-deily]

I guess I’ve now satisfied the cla bot even though that email address has been dead for many years ;)

[erlend-aasland]

@AA-Turner, are you ready for rebase-and-merge? 🚀

[AA-Turner]

Yessir! Hopefully all goes well...

[erlend-aasland]

Yessir! Hopefully all goes well...

Hm, perhaps a merge commit would be preferable to rebase in this case.

[AA-Turner]

There are some embedded merges (e.g. f57d28b) -- I don't know if a rebase-merge would linearise. A standard merge commit would work for certain.

[hugovk]

The enabled options are squash and merge, and rebase and merge.

[erlend-aasland]

I think a rebase-and-merge does something a la this:

$ git switch <pr-branch>
$ git rebase main  # put everything on "top" of main
$ git switch main
$ git merge --ff @{-1}  # fast-forward through the rebased branch

So, we'll end up with ~70 more commits after b70b763. Perhaps that's ok. Here's a local rebase-and-main of this PR:

$ git switch main
$ git pull
$ gh co 1160
$ git rebase main
$ git switch -
$ git merge --ff @{-1}
$ git log --oneline upstream/main.. | wc -l
    68

[erlend-aasland]

The enabled options are squash and merge, and rebase and merge.

Yeah, we'd need a repo admin to enable the merge option for a little while. But I'm not sure it's worth it.

[AA-Turner]

Let me try making a PR against my fork & rebase-merging

[AA-Turner]

It seems, unfortunately, that history is fully linearised with a rebase-merge:

https://github.com/AA-Turner/devguide/commits/main/

This branch (pre rebase-merge -- note the embedded branches)

$ git log upstream/main..migrate-argument-clinic-docs-rebase --oneline --graph --simplify-merges
* d400976 (origin/migrate-argument-clinic-docs-rebase, migrate-argument-clinic-docs-rebase, macdr-tmp) Adapt clinic.rst
* 2853c96 Add clinic.rst to Development Tools
* bb50117 Add clinic.rst with history
* 151a8c7 Docs: clean up Argument Clinic howto's (#107797)
* c312d0d gh-104683: Add --exclude option to Argument Clinic CLI (#107770)
* ed0c511 gh-86457: Add docs for Argument Clinic @text_signature directive (#107747)
* 5bdd8a1 gh-95065: Add Argument Clinic support for deprecating positional use of parameters (#95151)
* 9034038 Docs: Argument Clinic: Move the CConverter class to the reference (#107671)
* 8d09b74 Docs: Argument Clinic: Improve 'How to write a custom converter' (#107328)
* a4ae828 gh-107507: Replace 'The goals of Argument Clinic' with a summary (#107508)
* 66aa05c Docs: Argument Clinic: Restructure "Basic concepts and usage" (#106981)
* 8d22321 Docs: Remove the numbered steps from the Argument Clinic tutorial (#107203)
* 2886f0a Docs: Add missing markup to Argument Clinic docs (#106876)
* 344c441 Docs: Remove duplicate word in Argument Clinic howto heading (#107169)
* 3eef763 Docs: Argument Clinic: Add Background and Tutorial top-level sections (#106904)
* 415cecb Docs: Argument Clinic: Group guides about default values (#106872)
* a8eaf77 Docs: Normalise Argument Clinic advanced topics headings (#106842)
* e3fa19a Docs: Normalize Argument Clinic How-To section capitalization (#106788)
* 295ff8c gh-104389: Add 'unused' keyword to Argument Clinic C converters (#104390)
* fd1d602 gh-64658: Expand Argument Clinic return converter docs (#104175)
* e470d87 gh-98763: Prefer "python" over "python3" for command line examples in docs. (#98761)
* 57ffbb3 docs: Change links to label refs (#98454)
* 5a09524 gh-97956: Mention `generate_global_objects.py` in `AC How-To` (#97957)
* 4cd7406 gh-95007: Remove the NoneType return converter from Argument Clinic Doc (#95529)
* 31b05dc Docs: remove redundant "adverb-adjective" hyphens from compound modifiers (GH-94551)
* e500f1e Document Py_ssize_t. (GH-92512)
* 7c1e59b gh-92536: PEP 623: Remove wstr and legacy APIs from Unicode (GH-92537)
* 3c27a95 bpo-46613: Add PyType_GetModuleByDef to the public API (GH-31081)
* b24f012 bpo-45320: Remove long-deprecated inspect methods (GH-28618)
* a29a2f9 bpo-42048: Clinic Howto: Document AC's defining_class converter (GH-23978)
* bdcd2e0 bpo-38600: NULL -> ``NULL``. (GH-17001)
* aed5df8 Doc: Replace the deprecated highlightlang directive by highlight. (#13377)
* 51b5015 bpo-35042: Use the :pep: role where a PEP is specified (#10036)
* e2b893d bpo-20260: Implement non-bitwise unsigned int converters for Argument Clinic. (GH-8434)
* fca9801 Docs: be less specific about python versions (GH-6985)
* e8feb55 Improve highlighting of some code blocks. (GH-6401)
* c20fce3 bpo-29596: Improve clinic howto documentation (GH-1710)
* 41e583f bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
*   f6f3d84 Issue #28755: Merge Arg Clinic howto from 3.6
|\
| *   f57d28b Issues #28755, #28753: Merge Arg Clinic howto from 3.5
| |\
| | * a34489a Issue #28755: Improve syntax highlighting in Arg Clinic howto
| | * 45df510 Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
* | | a814275 Change an en-dash to an em-dash.
* | | bcd28d5 Merge doc fixups from 3.6
|\| |
| * | a084c1a Merge doc fixups from 3.5
| |\|
| | * 1acf9f1 Change double hyphens (en dashes) to em (longer) dashes
* | | 979f676 Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
|/ /
* / f296eec clinic: PY_LONG_LONG -> long long
|/
* a219cc1 Issue #27745: Fix some typos in Argument Clinic howto, by Lele Gaifax
* 42a5613 Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
* 43460f5 Issue #27626: Spelling fixes in docs, comments and internal names
* 8d02d63 Issue #27130: Fix handling of buffers exceeding UINT_MAX in “zlib” module
*   a8f1fd9 Issue #25626: Merge zlib fix from 3.5
|\
| * d3999f3 Issue #25626: Change zlib to accept Py_ssize_t and cap to UINT_MAX
* | f474f74 null merge 3.5 to default (9a0c5ffe7420 merged 3.4 to default, bypassing 3.5)
|\|
| *   521f916 null merge 3.4 to 3.5 (9a0c5ffe7420 merged 3.4 to default, bypassing 3.5)
| |\
* | \   44a5dd0 null merge with 3.4
|\ \ \
| |/ /
|/| /
| |/
| * ce0eea3 Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multiple documentation typos.
* | 9d3c415 Issue #24232: Fix typos. Patch by Ville Skyttä.
|\|
| * 1c71560 Issue #24232: Fix typos. Patch by Ville Skyttä.
* | 76f3c98 Argument Clinic: added missing bit of info in howto
* | 9932752 Issue #24000: Improved Argument Clinic's mapping of converters to legacy "format units".  Updated the documentation to match.
* | 1a50188 Fix Issue #21528 - Fix documentation typos
|/
* 397ed13 #Issue 20456: Several improvements and bugfixes for Argument Clinic, including correctly generating code for Clinic blocks inside C preprocessor conditional blocks.
* e68d632 Documentation fixes, including fixing "suspicious" problems.
* d1f7bad #20348: fix headers markup in Argument Clinic howto.  Patch by Moritz Neeb.
* a058a0e Doc fixes for Argument Clinic.
* 36ddfaa Issue #20294: Argument Clinic now supports argument parsing for __new__ and __init__ functions.
* 432d1c5 Doc improvements for Clinic howto "Goals" section.
* 2bbdb20 Issue #20287: Argument Clinic's output is now configurable, allowing delaying its output or even redirecting it to a separate file.
* 5cc73dc Issue #20226: Major improvements to Argument Clinic.
* 95b9ad1 Issue #20268: Argument Clinic now supports cloning the parameters and return converter from existing functions.
* cbad5d2 Minor doc fix in Clinic howto.
* 0729c14 Issue #20214: Fixed a number of small issues and documentation errors in Argument Clinic (see issue for details).
* 246016e Closes #20200: Argument Clinic custom converter example should be in a 'python' clinic block, not a 'clinic' clinic block.  Patch written by Ryan Smith-Roberts.
* f8f8a8a Issue #19273: The marker comments Argument Clinic uses have been changed to improve readability.
* 7324097 Issue #20141: Improved Argument Clinic's support for the PyArg_Parse "O!" format unit.
* 467c3ef Argument Clinic: fixed test suite, improved howto.
* 29b0880 Issue #19659: Added documentation for Argument Clinic.

My fork (post rebase-merge) -- note no branches

$ git log upstream/main..origin/main --oneline --graph --simplify-merges
* 6825c6e (origin/main) Adapt clinic.rst
* 6b83f2a Add clinic.rst to Development Tools
* 0912b4e Add clinic.rst with history
* 3614c6c Docs: clean up Argument Clinic howto's (#107797)
* 4c91a7d gh-104683: Add --exclude option to Argument Clinic CLI (#107770)
* 41c0a2d gh-86457: Add docs for Argument Clinic @text_signature directive (#107747)
* 9a08231 gh-95065: Add Argument Clinic support for deprecating positional use of parameters (#95151)
* a4a2f41 Docs: Argument Clinic: Move the CConverter class to the reference (#107671)
* 52e9a80 Docs: Argument Clinic: Improve 'How to write a custom converter' (#107328)
* 82a50e3 gh-107507: Replace 'The goals of Argument Clinic' with a summary (#107508)
* cf6f1a9 Docs: Argument Clinic: Restructure "Basic concepts and usage" (#106981)
* c0e1277 Docs: Remove the numbered steps from the Argument Clinic tutorial (#107203)
* dfd211b Docs: Add missing markup to Argument Clinic docs (#106876)
* 6172656 Docs: Remove duplicate word in Argument Clinic howto heading (#107169)
* 897bf32 Docs: Argument Clinic: Add Background and Tutorial top-level sections (#106904)
* 838112b Docs: Argument Clinic: Group guides about default values (#106872)
* da7f601 Docs: Normalise Argument Clinic advanced topics headings (#106842)
* fe2d48d Docs: Normalize Argument Clinic How-To section capitalization (#106788)
* 47f614c gh-104389: Add 'unused' keyword to Argument Clinic C converters (#104390)
* df452a4 gh-64658: Expand Argument Clinic return converter docs (#104175)
* 0c38d4b gh-98763: Prefer "python" over "python3" for command line examples in docs. (#98761)
* 3c0411c docs: Change links to label refs (#98454)
* 1f34c27 gh-97956: Mention `generate_global_objects.py` in `AC How-To` (#97957)
* 98510f9 gh-95007: Remove the NoneType return converter from Argument Clinic Doc (#95529)
* f135d64 Docs: remove redundant "adverb-adjective" hyphens from compound modifiers (GH-94551)
* 78d52d4 Document Py_ssize_t. (GH-92512)
* fb4a070 gh-92536: PEP 623: Remove wstr and legacy APIs from Unicode (GH-92537)
* 05650e7 bpo-46613: Add PyType_GetModuleByDef to the public API (GH-31081)
* 8da453d bpo-45320: Remove long-deprecated inspect methods (GH-28618)
* dacc8bf bpo-42048: Clinic Howto: Document AC's defining_class converter (GH-23978)
* 0117a9d bpo-38600: NULL -> ``NULL``. (GH-17001)
* f9fde8e Doc: Replace the deprecated highlightlang directive by highlight. (#13377)
* f9dcc92 bpo-35042: Use the :pep: role where a PEP is specified (#10036)
* 610ace1 bpo-20260: Implement non-bitwise unsigned int converters for Argument Clinic. (GH-8434)
* a314057 Docs: be less specific about python versions (GH-6985)
* 290fd75 Improve highlighting of some code blocks. (GH-6401)
* 0de8622 bpo-29596: Improve clinic howto documentation (GH-1710)
* 110adf4 bpo-29918: Add missed "const" modifiers in C API documentation. (#846)
* b17ea88 Issue #28755: Improve syntax highlighting in Arg Clinic howto
* 33188e3 Change an en-dash to an em-dash.
* 777e85b Change double hyphens (en dashes) to em (longer) dashes
* 551516f Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.
* 91259d6 clinic: PY_LONG_LONG -> long long
* e7fd394 Issue #27745: Fix some typos in Argument Clinic howto, by Lele Gaifax
* 4fadd2f Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting.
* 45eee05 Issue #27626: Spelling fixes in docs, comments and internal names
* 1d230bf Issue #27130: Fix handling of buffers exceeding UINT_MAX in “zlib” module
* 29ae29b Issue #25626: Change zlib to accept Py_ssize_t and cap to UINT_MAX
* dee5132 Issue #24232: Fix typos. Patch by Ville Skyttä.
* 748bbea Argument Clinic: added missing bit of info in howto
* e617cac Issue #24000: Improved Argument Clinic's mapping of converters to legacy "format units".  Updated the documentation to match.
* cc72f86 Fix Issue #21528 - Fix documentation typos
* d624f48 #Issue 20456: Several improvements and bugfixes for Argument Clinic, including correctly generating code for Clinic blocks inside C preprocessor conditional blocks.
* 59d789a Documentation fixes, including fixing "suspicious" problems.
* a71c6f3 #20348: fix headers markup in Argument Clinic howto.  Patch by Moritz Neeb.
* 97cd258 Doc fixes for Argument Clinic.
* 6ffe3ba Issue #20294: Argument Clinic now supports argument parsing for __new__ and __init__ functions.
* 07501c0 Doc improvements for Clinic howto "Goals" section.
* cb677af Issue #20287: Argument Clinic's output is now configurable, allowing delaying its output or even redirecting it to a separate file.
* 8255c89 Issue #20226: Major improvements to Argument Clinic.
* 4ab173e Issue #20268: Argument Clinic now supports cloning the parameters and return converter from existing functions.
* 5b0ce65 Minor doc fix in Clinic howto.
* 4d263f5 Issue #20214: Fixed a number of small issues and documentation errors in Argument Clinic (see issue for details).
* 220d083 Closes #20200: Argument Clinic custom converter example should be in a 'python' clinic block, not a 'clinic' clinic block.  Patch written by Ryan Smith-Roberts.
* 0f7c066 Issue #19273: The marker comments Argument Clinic uses have been changed to improve readability.
* 7e7dae0 Issue #20141: Improved Argument Clinic's support for the PyArg_Parse "O!" format unit.
* cc3f6d6 Argument Clinic: fixed test suite, improved howto.
* 32ca987 Issue #19659: Added documentation for Argument Clinic.

A

[AA-Turner]

The other (unforseen) downside of a rebase-merge is that it sets the committer for each commit to the person doing the merge (don't ask me why!):

A

[erlend-aasland]

The other (unforseen) downside of a rebase-merge is that it sets the committer for each commit to the person doing the merge (don't ask me why!):

Well, rebasing implies rewriting the Git history. I think a merge commit is the best way to land this.

[hugovk]

Becasue a rebase is rewriting history, and the rebaser is creating new commits with new SHAs. The original author/committer is preserved in an author trailer.

[AA-Turner]

I don't know who the admins are for the devguide repo (ironically, the devguide only lists the admins for the CPython repo!) -- is there an obvious way to find out that I'm missing?

[hugovk]

Scroll up a bit, there's a GitHub org owners list at https://devguide.python.org/developer-workflow/development-cycle/#current-owners

Is it really worth an exception in this case? I'm fine with the existing options of either squash and merge, or rebase and merge.

Everyone still gets credit in the commits, and the PR is still here to show all the old commits.

[AA-Turner]

GitHub org owners

Of course, forgot they had admin rights momentarily

Is it really worth an exception in this case? I'm fine with the existing options of either squash and merge, or rebase and merge.

Everyone still gets credit in the commits, and the PR is still here to show all the old commits.

I'd like to argue that it is. Moving histories like this PR does is fairly uncommon, but is also a 'one chance to get right' activity. Preserving the history properly allows for local (offline etc) inspection (this is often useful to me on trains/planes with poor or zero internet connection), proper git blame for working out the rationale of a change, etc.

A specific argument against using this PR as the history: When looking through the commit history of the PEPs or CPython the links to now-dead VCS hosts are too numerous to list. GitHub might be shut down in 20 years, or Python migrate to another DCVS host, (or another VCS), etc -- embedding the data in the repository itself, as intended by git, is the better thing to do here. Though it is more inconvenient to accomplish.

Sorry for the mild diatribe!
A

[erlend-aasland]

After sleeping on this, I'm fine with the rebase option. If we want, we can also rewrite the commit titles (gh-xxx => python/cpython#xxx), so the commit title links will work. What do you think?

[erlend-aasland]

After sleeping on this, I'm fine with the rebase option. If we want, we can also rewrite the commit titles (gh-xxx => python/cpython#xxx), so the commit title links will work. What do you think?

Like this: erlend-aasland#1

[erlend-aasland]

@AA-Turner, ready for rebase and merge?

[erlend-aasland]

Gentle ping, @AA-Turner :)

[AA-Turner]

Yep, no further changes from me.

A

[erlend-aasland]

🤞🚀