From 8cc408344d25c2d76f79a1fd41ebac5101064568 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 26 Jul 2023 18:34:35 +0200 Subject: [PATCH 1/2] gh-106948: Doc config ignores more standard C functions Complete nitpick_ignore list in Doc/conf.py to ignore more standard C functions, variables, macros, and also Win32 API functions and macros. No longer ignore "__int" C type: it should not be used in the doc. --- Doc/c-api/exceptions.rst | 2 +- Doc/c-api/sys.rst | 4 +-- Doc/conf.py | 78 +++++++++++++++++++++++++++++++++++++++- Doc/library/mailbox.rst | 8 ++--- Doc/library/os.rst | 6 ++-- Doc/library/signal.rst | 2 +- Doc/whatsnew/2.6.rst | 2 +- Misc/NEWS.d/3.10.0a1.rst | 2 +- 8 files changed, 90 insertions(+), 14 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 4d81b273638b14..3d4ceb360f5b18 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -163,7 +163,7 @@ For convenience, some of these functions will always return a This is a convenience function to raise an exception when a C library function has returned an error and set the C variable :c:data:`errno`. It constructs a tuple object whose first item is the integer :c:data:`errno` value and whose - second item is the corresponding error message (gotten from :c:func:`!strerror`), + second item is the corresponding error message (gotten from :c:func:`strerror`), and then calls ``PyErr_SetObject(type, object)``. On Unix, when the :c:data:`errno` value is :c:macro:`EINTR`, indicating an interrupted system call, this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst index 6a717122c8a2f8..433d69e40f947a 100644 --- a/Doc/c-api/sys.rst +++ b/Doc/c-api/sys.rst @@ -106,7 +106,7 @@ Operating System Utilities .. c:function:: PyOS_sighandler_t PyOS_getsig(int i) Return the current signal handler for signal *i*. This is a thin wrapper around - either :c:func:`!sigaction` or :c:func:`!signal`. Do not call those functions + either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void (\*)(int)`. @@ -114,7 +114,7 @@ Operating System Utilities .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h) Set the signal handler for signal *i* to be *h*; return the old signal handler. - This is a thin wrapper around either :c:func:`!sigaction` or :c:func:`!signal`. Do + This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:expr:`void (\*)(int)`. diff --git a/Doc/conf.py b/Doc/conf.py index 8821a2a172f11d..634e461c759dd3 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -78,26 +78,78 @@ nitpick_ignore = [ # Standard C functions + ('c:func', '_exit'), + ('c:func', '_stricmp'), + ('c:func', 'abort'), + ('c:func', 'atof'), ('c:func', 'calloc'), + ('c:func', 'close'), + ('c:func', 'ctime'), ('c:func', 'dlopen'), ('c:func', 'exec'), + ('c:func', 'exit'), ('c:func', 'fcntl'), + ('c:func', 'flock'), ('c:func', 'fork'), ('c:func', 'free'), + ('c:func', 'fstat'), + ('c:func', 'fsync'), + ('c:func', 'getsid'), + ('c:func', 'gettimeofday'), ('c:func', 'gmtime'), + ('c:func', 'inet_aton'), + ('c:func', 'inet_pton'), + ('c:func', 'ioctl'), + ('c:func', 'localeconv'), ('c:func', 'localtime'), + ('c:func', 'lockf'), + ('c:func', 'lstat'), ('c:func', 'main'), ('c:func', 'malloc'), + ('c:func', 'memcpy'), + ('c:func', 'memmove'), + ('c:func', 'mktime'), + ('c:func', 'mmap'), + ('c:func', 'munmap'), + ('c:func', 'open'), + ('c:func', 'perror'), + ('c:func', 'posix_spawn'), + ('c:func', 'posix_spawn_file_actions_addclose'), + ('c:func', 'posix_spawn_file_actions_adddup2'), + ('c:func', 'posix_spawn_file_actions_addopen'), + ('c:func', 'posix_spawnp'), ('c:func', 'printf'), + ('c:func', 'putenv'), + ('c:func', 'qsort'), ('c:func', 'realloc'), + ('c:func', 'select'), + ('c:func', 'setenv'), + ('c:func', 'setpgid'), + ('c:func', 'setpgrp'), + ('c:func', 'setsid'), + ('c:func', 'setsockopt'), + ('c:func', 'sigaction'), + ('c:func', 'sigaltstack'), + ('c:func', 'siginterrupt'), + ('c:func', 'signal'), ('c:func', 'snprintf'), + ('c:func', 'splice'), ('c:func', 'sprintf'), ('c:func', 'stat'), + ('c:func', 'statvfs'), + ('c:func', 'strcasecmp'), + ('c:func', 'strcmp'), + ('c:func', 'strerror'), + ('c:func', 'strlen'), + ('c:func', 'strncmp'), ('c:func', 'system'), + ('c:func', 'unsetenv'), ('c:func', 'vsnprintf'), + ('c:func', 'vsprintf'), + # Standard C types ('c:type', 'FILE'), - ('c:type', '__int'), + ('c:type', 'int64_t'), ('c:type', 'intmax_t'), ('c:type', 'off_t'), ('c:type', 'ptrdiff_t'), @@ -105,16 +157,40 @@ ('c:type', 'size_t'), ('c:type', 'ssize_t'), ('c:type', 'time_t'), + ('c:type', 'uint64_t'), ('c:type', 'uintmax_t'), + ('c:type', 'uintptr_t'), ('c:type', 'va_list'), + ('c:type', 'wchar'), ('c:type', 'wchar_t'), + # Standard C macros + ('c:macro', 'EDOM'), + ('c:macro', 'EINTR'), ('c:macro', 'LLONG_MAX'), ('c:macro', 'LLONG_MIN'), ('c:macro', 'LONG_MAX'), ('c:macro', 'LONG_MIN'), + # Standard C variables ('c:data', 'errno'), + + # Win32 API functions + ('c:func', 'FormatMessage'), + ('c:func', 'GetFileInformationByHandle'), + ('c:func', 'GetLastError'), + ('c:func', 'GetVersionEx'), + ('c:func', 'MessageBeep'), + ('c:func', 'PlaySound'), + ('c:func', 'ShellExecute'), + ('c:func', 'TerminateProcess'), + ('c:func', 'VirtualAlloc'), + ('c:func', 'VirtualFree'), + ('c:func', 'WSAIoctl'), + + # Win32 API macros + ('c:macro', 'CP_ACP'), + # Standard environment variables ('envvar', 'BROWSER'), ('envvar', 'COLUMNS'), diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 91df07d914cae2..56908dedea1b40 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -477,7 +477,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :c:func:`!flock` and :c:func:`!lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: @@ -588,7 +588,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :c:func:`!flock` and :c:func:`!lockf` system calls. For MH mailboxes, locking + :c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking the mailbox means locking the :file:`.mh_sequences` file and, only for the duration of any operations that affect them, locking individual message files. @@ -686,7 +686,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :c:func:`!flock` and :c:func:`!lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: @@ -737,7 +737,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unlock() Three locking mechanisms are used---dot locking and, if available, the - :c:func:`!flock` and :c:func:`!lockf` system calls. + :c:func:`flock` and :c:func:`lockf` system calls. .. seealso:: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index bbf227aab649e2..57405916ed7b31 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -714,14 +714,14 @@ process and user. .. function:: getsid(pid, /) - Call the system call :c:func:`!getsid`. See the Unix manual for the semantics. + Call the system call :c:func:`getsid`. See the Unix manual for the semantics. .. availability:: Unix, not Emscripten, not WASI. .. function:: setsid() - Call the system call :c:func:`!setsid`. See the Unix manual for the semantics. + Call the system call :c:func:`setsid`. See the Unix manual for the semantics. .. availability:: Unix, not Emscripten, not WASI. @@ -739,7 +739,7 @@ process and user. .. function:: strerror(code, /) Return the error message corresponding to the error code in *code*. - On platforms where :c:func:`!strerror` returns ``NULL`` when given an unknown + On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown error number, :exc:`ValueError` is raised. diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index e53315bee3ea3e..523d1ac5001360 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -562,7 +562,7 @@ The :mod:`signal` module defines the following functions: Note that installing a signal handler with :func:`signal` will reset the restart behaviour to interruptible by implicitly calling - :c:func:`!siginterrupt` with a true *flag* value for the given signal. + :c:func:`siginterrupt` with a true *flag* value for the given signal. .. function:: signal(signalnum, handler) diff --git a/Doc/whatsnew/2.6.rst b/Doc/whatsnew/2.6.rst index ad899d53886c59..ae06d3bbc7eff1 100644 --- a/Doc/whatsnew/2.6.rst +++ b/Doc/whatsnew/2.6.rst @@ -2982,7 +2982,7 @@ Changes to Python's build process and to the C API include: * Python now must be compiled with C89 compilers (after 19 years!). This means that the Python source tree has dropped its - own implementations of :c:func:`!memmove` and :c:func:`!strerror`, which + own implementations of :c:func:`memmove` and :c:func:`strerror`, which are in the C89 standard library. * Python 2.6 can be built with Microsoft Visual Studio 2008 (version diff --git a/Misc/NEWS.d/3.10.0a1.rst b/Misc/NEWS.d/3.10.0a1.rst index 79d85a40df8bbe..7d2ab223e34abc 100644 --- a/Misc/NEWS.d/3.10.0a1.rst +++ b/Misc/NEWS.d/3.10.0a1.rst @@ -229,7 +229,7 @@ format string in f-string and :meth:`str.format`. The implementation of :func:`signal.siginterrupt` now uses :c:func:`!sigaction` (if it is available in the system) instead of the -deprecated :c:func:`!siginterrupt`. Patch by Pablo Galindo. +deprecated :c:func:`siginterrupt`. Patch by Pablo Galindo. .. From 596198de5d0a7fb1169e08f7337d27c8ce93936c Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Wed, 26 Jul 2023 18:57:08 +0200 Subject: [PATCH 2/2] Update Doc/tools/.nitignore --- Doc/tools/.nitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 07123bcb5ae064..de8f8faf809fe1 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -12,8 +12,6 @@ Doc/c-api/capsule.rst Doc/c-api/cell.rst Doc/c-api/code.rst Doc/c-api/codec.rst -Doc/c-api/complex.rst -Doc/c-api/conversion.rst Doc/c-api/datetime.rst Doc/c-api/descriptor.rst Doc/c-api/exceptions.rst @@ -200,7 +198,6 @@ Doc/library/urllib.request.rst Doc/library/uuid.rst Doc/library/weakref.rst Doc/library/winreg.rst -Doc/library/winsound.rst Doc/library/wsgiref.rst Doc/library/xml.dom.minidom.rst Doc/library/xml.dom.pulldom.rst