Docs: Improve Argument Clinic tutorial preamble #107323
Conversation
Align with Diátaxis principles: - Provide a complete picture before the tutorial starts - Ignore options and alternatives: move suggested follow-up reading to the end of the tutorial, in the form of `.. seealso::`
erlend-aasland
added
skip issue
skip news
needs backport to 3.11
| First, make sure you're working with a freshly updated checkout | ||
| of the CPython trunk. |
There was a problem hiding this comment.
I don't think this brings much value in the tutorial. The tutorial is targeted at the core dev and contributor audience; working on an old checkout seems like a very little likely scenario, IMO.
There was a problem hiding this comment.
While they know, it might be useful as a reminder. If being a few commits behind is not an issue, then the reminder is not essential and can be removed.
There was a problem hiding this comment.
I think the tutorial currently mixes two things:
- using a specific example (pickle.Pickler.dump)
- trying to teach general guidelines for how to apply clinic to CPython (if x, then don't do y, if z then you can do w, etc.)
I'd like the tutorial to be repeatable and to not drift into digression after digression. The sentence in question could be a part of a "How to apply Argument Clinic to CPython" recipe, instead of part of the tutorial.
There was a problem hiding this comment.
I think it'll be hard to align the tutorial according to Diátaxis principles until we've extracted the "how to apply Argument Clinic to CPython" bits from it. Perhaps we should do that first.
What do you think, @ezio-melotti?
| Next, take a look at the format string of the :c:func:`!PyArg_Parse*` call. | ||
| If it contains any of the following format units...: |
There was a problem hiding this comment.
We should consider removing this from the tutorial, in my opinion. Alternatives and information are tutorial anti-patterns.
There was a problem hiding this comment.
You could state what format units are relevant for the tutorial, and link to the advanced converters section for the others. IOW state what works, rather than what doesn't work.
|
@ezio-melotti, are you ok with reviewing these? If you're not super-interested in reviewing Argument Clinic Diátaxis PRs, don't hesitate to let me know :) |
| First, make sure you're working with a freshly updated checkout | ||
| of the CPython trunk. |
There was a problem hiding this comment.
While they know, it might be useful as a reminder. If being a few commits behind is not an issue, then the reminder is not essential and can be removed.
| In this tutorial, you will convert a C function from having custom | ||
| :ref:`argument parsing code <arg-parsing>` | ||
| to using Argument Clinic to generate that boilerplate code. |
There was a problem hiding this comment.
I feel this sentence could be better, maybe something like:
| In this tutorial, you will convert a C function from having custom | |
| :ref:`argument parsing code <arg-parsing>` | |
| to using Argument Clinic to generate that boilerplate code. | |
| In this tutorial, you will learn how to use Argument Clinic to generate | |
| :ref:`argument parsing code <arg-parsing>` for a function that | |
| was using custom code. |
The current sentence uses the imperative form to tell you what to do, without telling you why, in a way that sounds a bit harsh. "Converting a function" seems something an howto would cover, whereas "learn how to use AC (to convert functions)" seems a better fit for the tutorial.
In addition, using "we" ("we will learn how") sounds "friendlier" to me, even thought technically only the reader is learning. This might require a refactoring of the whole tutorial, even though I see there are some instances of "we" later. I don't remember if diataxis has any preference regarding this.
| Next, take a look at the format string of the :c:func:`!PyArg_Parse*` call. | ||
| If it contains any of the following format units...: |
There was a problem hiding this comment.
You could state what format units are relevant for the tutorial, and link to the advanced converters section for the others. IOW state what works, rather than what doesn't work.
Yep, and if some PR is blocking you and needs review you can ping me on Discord. I try to keep up with my GitHub notifications, but sometimes I fall a couple of days behind and/or wait until I have a bigger chunk of free time before I go through them. These PRs are generally quick to review, so they are not an issue and I can find 5 minutes for them. |
|
I've marked this as a draft, as I believe this PR was premature; we need to separate out the "how to apply AC to CPython" parts from the tutorial first. Then we can start improving the text. |
Instead of repeating the rationale and motivation of PEP-436, reword the Abstract to provide a summary of the goals of AC.
|
Argument Clinic has moved to the devguide. A new PR will have to be opened against that repo. |
Align with Diátaxis principles:
the end of the tutorial, in the form of
.. seealso::Also:
📚 Documentation preview 📚: https://cpython-previews--107323.org.readthedocs.build/