gh-106033: [docs] Improve C API GetItem & HasAttr notes. #106047
Conversation
This should format the notes and call out the preferred APIs to use in a more visible manner.
gpshead
added
docs
|
In the docs preview these notes render well and are much more obvious than the previous plain text paragraph: https://cpython-previews--106047.org.readthedocs.build/en/106047/c-api/dict.html#c.PyDict_GetItem I changed the "suppressed" wording to "silently ignored" but I'm not sure that is any better. swallowed, eaten, and discarded also come to mind. thoughts? |
There was a problem hiding this comment.
Standard reminder: You can directly apply all the suggestions you want in one go by going to Files changed -> Clicking Add to batch on each suggestion -> When done, clicking Commit
Two sets of suggestions:
- Given this is cautioning/warning against problematic behavior, I suggest using the appropriate admonition type accordingly.
- Fix a number of broken references (to generic dunder methods) introduced in this PR.
Other than that, LGTM, thanks! It is definitely an improvement, as you say.
Not a C API expert of course, but to me "silently ignored" sounded more appropriate in terms of affect/implications than "suppressed", since the latter implies a deliberate, purposeful act while the former better conveys this is a potentially undesired side effect. "Swallowed" and "eaten" are potentially more negative, but also more informal for technical documentation and potentially decreases the gravity of the note, and "discarded" sounds somewhere between "suppressed" and "silently ignored" to me, or about the same, so I'm fine with "silently ignored" personally. |
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
ironically stands out less than note, but the bold caution: is still sufficient and better than what we had. warning would stand out too much. Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
ironically stands out less than note, but the bold caution: is still sufficient and better than what we had. warning would stand out too much. Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
There was a problem hiding this comment.
Would be LGTM, but it seems the Python docs theme is entirely missing appropriate styles for caution admonitions—they are not only lacking an appropriate color, but are entirely missing the whole callout box around them, too.
Therefore, until that is fixed, you'll have to either go back to using note, or step it up to warning (as is used elsewhere).
|
Thanks @gpshead for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12. |
…nGH-106047) Use a note:: tag so that these dict and object API deficiencies show up clearly. A caution:: tag was considered, but our current python docs rendering doesn't do much with that (no box or color change). warning:: seemed too extreme. note looks good. (cherry picked from commit 19d6511) Co-authored-by: Gregory P. Smith <greg@krypto.org>
…nGH-106047) Use a note:: tag so that these dict and object API deficiencies show up clearly. A caution:: tag was considered, but our current python docs rendering doesn't do much with that (no box or color change). warning:: seemed too extreme. note looks good. (cherry picked from commit 19d6511) Co-authored-by: Gregory P. Smith <greg@krypto.org>
|
GH-106070 is a backport of this pull request to the 3.12 branch. |
|
GH-106071 is a backport of this pull request to the 3.11 branch. |
…06047) (#106071) gh-106033: [docs] Improve C API GetItem & HasAttr notes. (GH-106047) Use a note:: tag so that these dict and object API deficiencies show up clearly. A caution:: tag was considered, but our current python docs rendering doesn't do much with that (no box or color change). warning:: seemed too extreme. note looks good. (cherry picked from commit 19d6511) Co-authored-by: Gregory P. Smith <greg@krypto.org>
…06047) (#106070) gh-106033: [docs] Improve C API GetItem & HasAttr notes. (GH-106047) Use a note:: tag so that these dict and object API deficiencies show up clearly. A caution:: tag was considered, but our current python docs rendering doesn't do much with that (no box or color change). warning:: seemed too extreme. note looks good. (cherry picked from commit 19d6511) Co-authored-by: Gregory P. Smith <greg@krypto.org>
This should format the notes and call out the preferred APIs to use in a more visible manner.
📚 Documentation preview 📚: https://cpython-previews--106047.org.readthedocs.build/