Skip to content

Migrate Argument Clinic docs from the CPython repo to the devguide #1148

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
3 tasks done
erlend-aasland opened this issue Aug 2, 2023 · 5 comments · Fixed by #1160
Closed
3 tasks done

Migrate Argument Clinic docs from the CPython repo to the devguide #1148

erlend-aasland opened this issue Aug 2, 2023 · 5 comments · Fixed by #1160

Comments

@erlend-aasland
Copy link
Contributor

erlend-aasland commented Aug 2, 2023

See topic on Discourse and python/cpython#107518

Prerequisites:

  • Where should clinic.rst live?
  • Which section (and sub-section) should the Argument Clinic docs live in? (Advanced Tools? CPython Internals?)
  • Prepare devguide; rename Advanced Tools to Development Tools, and move it between Testing and Buildbots and Core Developers
@erlend-aasland
Copy link
Contributor Author

Perhaps the Development Workflow is a good fit. It already contains a section about writing extension modules (although that's just a collection of links).

@erlend-aasland
Copy link
Contributor Author

@CAM-Gerlach
Copy link
Member

I really struggled with that too when you first posed the issue of moving it; of the plausible candidates:

  • Development Workflow is the most crowded and is mostly focused on how to change different things rather than technical guides to specific tools, and currently has a clear and carefully thought out progression from giving an overview of CPython's development workflow and cycle to discussing how to make progressively larger and less common changes (from stdlib tweaks to porting to a whole new platform). Its not obvious where Argument Clinic would fit there (except at the end, but it still seems a little out of place).
  • CPython's Internals is mostly focused on explanation type content of how and why different parts of CPython work the way they do, rather than how-to guides on how to develop CPython or use specific tools, so doesn't seem like a good fit.
  • Advanced Tools is another option to consider, as it specifically covers how to use various tools for CPython development, so is at least nominally the most on-topic. It currently mostly focused on "advanced" tools (like GDB, Clang dynamic analysis, and Coverity) that won't be used by most CPython developers, so folks might not think to look there first. However, a rename to "Development Tools", a move to between Testing and Buildbots and Core Developers, and putting the Argument Clinic guide in the section first might help address that, as well as be a good spot for similar such guides in the future.

Therefore, my preference would be for Development Tools (Advanced Tools) with the changes suggested above.

@erlend-aasland
Copy link
Contributor Author

Development Tools sounds good to me!

@erlend-aasland
Copy link
Contributor Author

See #1149

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants