8000 Docs: Argument Clinic: Add Background and Tutorial top-level sections by erlend-aasland · Pull Request #106904 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Docs: Argument Clinic: Add Background and Tutorial top-level sections #106904

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.

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 21, 2023
Merged

Docs: Argument Clinic: Add Background and Tutorial top-level sections #106904

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
62723cf
Docs: Add Background and Tutorial top-level sections
erlend-aasland Jul 19, 2023
532dd98
Style
erlend-aasland Jul 19, 2023
de44907
Remove spurious change
erlend-aasland Jul 19, 2023
c900340
Address review: need three dashes for em-dash
erlend-aasland Jul 19, 2023
173e7fa
Pull in main
erlend-aasland Jul 20, 2023
c1bf977
Address review
erlend-aasland Jul 20, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 27 additions & 9 deletions Doc/howto/clinic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,20 @@ Argument Clinic How-To

Argument Clinic is a preprocessor for CPython C files.
Its purpose is to automate all the boilerplate involved
with writing argument parsing code for "builtins".
This document shows you how to convert your first C
function to work with Argument Clinic, and then introduces
some advanced topics on Argument Clinic usage.
with writing argument parsing code for "builtins",
module level functions, and class methods.
This document is divided in three major sections:

Currently Argument Clinic is considered internal-only
* :ref:`clinic-background` talks about the basic concepts and goals of
Argument Clinic.
* :ref:`clinic-tutorial` guides you through all the steps required to
adapt an existing C function to Argument Clinic.
* :ref:`clinic-howtos` details how to handle specific tasks.


.. note::

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
Expand All @@ -28,8 +36,14 @@ Argument Clinic How-To
of CPython *could* be totally incompatible and break all your code.


.. _clinic-background:

Background
==========


The goals of Argument Clinic
============================
----------------------------

Argument Clinic's primary goal
is to take over responsibility for all argument parsing code
Expand Down Expand Up @@ -80,7 +94,7 @@ things with all the information you give it.


Basic concepts and usage
========================
------------------------

Argument Clinic ships with CPython; you'll find it in ``Tools/clinic/clinic.py``.
If you run that script, specifying a C file as an argument:
Expand Down Expand Up @@ -142,8 +156,10 @@ For the sake of clarity, here's the terminology we'll use with Argument Clinic:
a block.)


Converting your first function
==============================
.. _clinic-tutorial:

Tutorial
========

The best way to get a sense of how Argument Clinic works is to
convert a function to work with it. Here, then, are the bare
Expand Down Expand Up @@ -560,6 +576,8 @@ Let's dive in!
Congratulations, you've ported your first function to work with Argument Clinic!


.. _clinic-howtos:

How-to guides
=============

Expand Down
0