gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst by smontanaro · Pull Request #114825 · python/cpython

smontanaro · 2024-01-31T22:47:14Z

This PR cleans up several bits in Doc/c-api/exceptions.rst:

suppress link to warnings.WarningMessage. It's not actually documented and isn't exposed by warnings.__all__. It's just a basic exception carrying around a message.
suppress link for __module__ attribute. The good stuff is in the containing paragraph.
suppress link for USE_STACKCHECK. The good stuff is in the documentation of PyOS_CheckStack, which is linked from the containing paragraph.
suppress links for three aliases for PyExc_OSError.

Since I was hunting down USE_STACKCHECK, I went ahead and suppressed the reference in Doc/c-api/sys.rst, in the documentation for PyOS_CheckStack.

I updated Doc/tools/.nitignore to remove Doc/c-api/exceptions.rst, but left an entry for Doc/c-api/sys.rst, as I didn't make an attempt to address any other problems it might have.

Issue: Fix all Sphinx reference warnings in the documentation #101100

📚 Documentation preview 📚: https://cpython-previews--114825.org.readthedocs.build/

…AuditHookFunction

serhiy-storchaka

If you want to specify their declaration, you can simply use typedef-like syntax.

I would move the Py_AuditHookFunction definition directly into PySys_AddAuditHook definition where it is only used. You need to add .. c:namespace:: NULL before it to avoid adding a prefix.

The PyOS_sighandler_t definition can be moved closer to PyOS_getsig() or PyOS_setsig() definitions. Duplicated description of PyOS_sighandler_t can be removed.

smontanaro · 2024-02-08T20:14:35Z

Thanks @serhiy-storchaka, I believe I folded in your suggestions in a reasonable way.

serhiy-storchaka

It deviated significantly from initial "clean up Doc/c-api/exceptions.rst", isn't? 😉 Maybe split it on several PRs? The auditing part is not trivial.

LGTM after you do something with duplication for Py_AuditHookFunction. For example:

 .. c:namespace::NULL .. c:type::int (*Py_AuditHookFunction) (constchar *event, PyObject *args, void *userData)
The type of the hook function.
*event* is (the event argument passed to PySys_Audit() or PySys_AuditTuple()),
*args* is (...), *userData* is (the argument passed to PySys_AddAuditHook()).
The hook function is always called ...
See :pep:`578` for ...

smontanaro · 2024-02-09T13:01:52Z

Feature creep is no problem. I'm retired, so have plenty of time to mess around. ;-)

Since it seems like I might have to write an actual sentence to flesh out this paragraph, I'm going to spend a bit of time reading PEP 578, but I'll have something later today.

serhiy-storchaka · 2024-02-09T20:25:52Z

+ .. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData)
+
+ The type of the hook function.
+ *event* is (the event argument passed to PySys_Audit() or PySys_AuditTuple()),


Wait, I used parentheses to denote that it is a preliminary text, and that you should rewrite it in good English. Perhaps it is even better to describe parameters not in terms of PySys_Audit() or PySys_AuditTuple(), but in more general terms. Look at sys.audit(). Perhaps "event is a C string identifying the event" is enough.

Ah, I recognized "(...)" as a placeholder, not the more elaborate parenthesized phrasing. Will get back to it.

Perhaps "event is a C string identifying the event" is enough.
I thought about that, but am not familiar enough with the C API documentation to know that descriptions of function prototypes don't simply rely on the actual prototype.

serhiy-storchaka · 2024-02-10T07:19:45Z

+.. c:namespace:: NULL
+.. c:type:: int (*Py_AuditHookFunction) (const char *event, PyObject *args, void *userData)


If it is not nested, c:namespace is not needed. I would prefer to make it nested, but it is only my personal preference.

serhiy-storchaka · 2024-02-10T07:20:47Z

+ If the interpreter is initialized, this function raises an auditing event
+ ``sys.addaudithook`` with no arguments. If any existing hooks raise an
+ exception derived from :class:`Exception`, the new hook will not be
+ added and the exception is cleared. As a result, callers cannot assume
+ that their hook has been added unless they control all existing hooks.


Why is it dedented? It belongs to the audit-event directive.

…works

smontanaro · 2024-02-10T19:24:00Z

Sorry, I clearly don't understand the functional implications of the indentation. See if this latest version is more correct.

serhiy-storchaka

LGTM.

miss-islington-app · 2024-02-11T18:51:11Z

Thanks @smontanaro for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

…rst (pythonGH-114825) (cherry picked from commit e1552fd) Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>

miss-islington-app · 2024-02-11T18:51:19Z

Sorry, @smontanaro and @serhiy-storchaka, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker e1552fd19de17e7a6daa3c2a6d1ca207bb8eaf8e 3.11

bedevere-app · 2024-02-11T18:51:20Z

GH-115308 is a backport of this pull request to the 3.12 branch.

….rst (GH-114825) (GH-115308) (cherry picked from commit e1552fd) Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>

smontanaro · 2024-02-11T19:05:48Z

@serhiy-storchaka I'll take care of the 3.11 conflict (I need the practice).

…rst (pythonGH-114825) (cherry picked from commit e1552fd)

bedevere-app · 2024-02-11T19:25:20Z

GH-115311 is a backport of this pull request to the 3.11 branch.

….rst (GH-114825) (GH-115311) (cherry picked from commit e1552fd)

…rst (pythonGH-114825)

clean up Doc/c-api/exceptions.rst
5342ffc

bedevere-appBot added docs Documentation in the Doc dir skip news awaiting review labels Jan 31, 2024

bedevere-appBot mentioned this pull request Jan 31, 2024
Fix all Sphinx reference warnings in the documentation #101100
Closed

AlexWaygood mentioned this pull request Feb 4, 2024
gh-101100: Fix Py_DEBUG dangling references #115003
Merged

serhiy-storchaka reviewed Feb 8, 2024
View reviewed changes

Comment threadDoc/c-api/sys.rst
Comment threadDoc/c-api/exceptions.rst Outdated

smontanaro added 2 commits February 8, 2024 11:00

typo caught by serhiy
d8a1b7a

+ USE_STACKCHECK index entry, type defs for PyOS_sighandler_t and Py_…
384f1c6
…AuditHookFunction

serhiy-storchaka reviewed Feb 8, 2024
View reviewed changes

Comment threadDoc/c-api/sys.rst Outdated
Comment threadDoc/c-api/sys.rst Outdated

feedback from Serhiy
e721a94

serhiy-storchaka reviewed Feb 8, 2024
View reviewed changes

Comment threadDoc/c-api/sys.rst Outdated

move location and context, per Serhiy
0a428a3

serhiy-storchaka reviewed Feb 9, 2024
View reviewed changes

tweak to eliminate duplicate, based on suggestion by Serhiy
2aa2771

serhiy-storchaka reviewed Feb 9, 2024
View reviewed changes

smontanaro added 2 commits February 9, 2024 16:02

maybe this is better
bf7297c

better ordering?
30427f5

serhiy-storchaka reviewed Feb 10, 2024
View reviewed changes

undoing some indentation, I clearly don't understand how the nesting …
bba6ff6
…works

serhiy-storchaka approved these changes Feb 11, 2024
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting review labels Feb 11, 2024

serhiy-storchaka enabled auto-merge (squash) February 11, 2024 18:42

Update .nitignore
67c1ac2

serhiy-storchaka disabled auto-merge February 11, 2024 18:44

Merge branch 'main' into doc-capi
f96de13

serhiy-storchaka enabled auto-merge (squash) February 11, 2024 18:45

serhiy-storchaka added needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Feb 11, 2024

serhiy-storchaka changed the title ~~gh-101100: clean up Doc/c-api/exceptions.rst~~gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rstFeb 11, 2024

serhiy-storchaka merged commit e1552fd into python:mainFeb 11, 2024

bedevere-appBot removed the awaiting merge label Feb 11, 2024

miss-islington-appBot assigned serhiy-storchaka Feb 11, 2024

bedevere-appBot removed the needs backport to 3.12 only security fixes label Feb 11, 2024

smontanaro deleted the doc-capi branch February 11, 2024 18:57

serhiy-storchaka pushed a commit that referenced this pull request Feb 11, 2024
[3.12]gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys…
6768860
….rst (GH-114825) (GH-115308) (cherry picked from commit e1552fd) Co-authored-by: Skip Montanaro <skip.montanaro@gmail.com>

smontanaro added a commit to smontanaro/cpython that referenced this pull request Feb 11, 2024
pythongh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.…
a11aab8
…rst (pythonGH-114825) (cherry picked from commit e1552fd)

smontanaro mentioned this pull request Feb 11, 2024
[3.11] Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst #114825 (gh-101100) #115310
Closed

bedevere-appBot removed the needs backport to 3.11 only security fixes label Feb 11, 2024

hugovk mentioned this pull request Feb 12, 2024
[3.11] gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.rst (#114825) #115311
Merged

serhiy-storchaka pushed a commit that referenced this pull request Feb 12, 2024
[3.11]gh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys…
07fff60
….rst (GH-114825) (GH-115311) (cherry picked from commit e1552fd)

fsc-eriker pushed a commit to fsc-eriker/cpython that referenced this pull request Feb 14, 2024
pythongh-101100: Clean up Doc/c-api/exceptions.rst and Doc/c-api/sys.…
8bae02d
…rst (pythonGH-114825)

serhiy-storchaka removed their assignment Jul 15, 2026

		.. c:namespace:: NULL
		.. c:type:: int (Py_AuditHookFunction) (const char event, PyObject args, void userData)

Uh oh!

Uh oh!

Conversation

smontanaro commented Jan 31, 2024• edited by github-actions BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

smontanaro commented Feb 8, 2024

Uh oh!

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

smontanaro commented Feb 9, 2024

Uh oh!

serhiy-storchakaFeb 9, 2024

Choose a reason for hiding this comment

Uh oh!

smontanaroFeb 9, 2024

Choose a reason for hiding this comment

Uh oh!

smontanaroFeb 9, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serhiy-storchakaFeb 10, 2024

Choose a reason for hiding this comment

Uh oh!

serhiy-storchakaFeb 10, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smontanaro commented Feb 10, 2024

Uh oh!

serhiy-storchaka left a comment

Choose a reason for hiding this comment

Uh oh!

miss-islington-appBot commented Feb 11, 2024

Uh oh!

miss-islington-appBot commented Feb 11, 2024

Uh oh!

bedevere-appBot commented Feb 11, 2024

Uh oh!

smontanaro commented Feb 11, 2024

Uh oh!

bedevere-appBot commented Feb 11, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

smontanaro commented Jan 31, 2024•
edited by github-actions Bot
Loading