gh-101100: Fix broken xrefs in fcntl module doc (#115691)

* clean up fcntl module doc

* simplify

* a few changes, based on suggestion by CAM-Gerlach

* nitpick ignore for a couple other C functions mentioned in the fcntl module doc

* more changes, especially related to LOCK_* constants

* :data: back to :const:

* Apply suggestions from code review

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
---------

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

diff --git a/Doc/conf.py b/Doc/conf.py
index 7c4817320a7de2c59529458928909f7b1dc8cb82..f4c75c5758cb28185161f78ce226a55d58c36590 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -101,11 +101,13 @@ nitpick_ignore = [
     ('c:func', 'dlopen'),
     ('c:func', 'exec'),
     ('c:func', 'fcntl'),
+    ('c:func', 'flock'),
     ('c:func', 'fork'),
     ('c:func', 'free'),
     ('c:func', 'gettimeofday'),
     ('c:func', 'gmtime'),
     ('c:func', 'grantpt'),
+    ('c:func', 'ioctl'),
     ('c:func', 'localeconv'),
     ('c:func', 'localtime'),
     ('c:func', 'main'),

diff --git a/Doc/library/fcntl.rst b/Doc/library/fcntl.rst
index 13ad2dd7da5090afdd331df74ddbe7614470caba..b93d6ac7aab95654c251727def628430fd89a7b8 100644 (file)
--- a/Doc/library/fcntl.rst
+++ b/Doc/library/fcntl.rst
@@ -13,10 +13,10 @@
 
 ----------------
 
-This module performs file control and I/O control on file descriptors. It is an
-interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.  For a
-complete description of these calls, see :manpage:`fcntl(2)` and
-:manpage:`ioctl(2)` Unix manual pages.
+This module performs file and I/O control on file descriptors. It is an
+interface to the :c:func:`fcntl` and :c:func:`ioctl` Unix routines.
+See the :manpage:`fcntl(2)` and :manpage:`ioctl(2)` Unix manual pages
+for full details.
 
 .. availability:: Unix, not Emscripten, not WASI.
 
@@ -101,7 +101,7 @@ The module defines the following functions:
    most likely to result in a segmentation violation or a more subtle data
    corruption.
 
-   If the :c:func:`fcntl` fails, an :exc:`OSError` is raised.
+   If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
 
    .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
 
@@ -139,7 +139,7 @@ The module defines the following functions:
    buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
    into the supplied buffer.
 
-   If the :c:func:`ioctl` fails, an :exc:`OSError` exception is raised.
+   If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
 
    An example::
 
@@ -164,7 +164,7 @@ The module defines the following functions:
    :manpage:`flock(2)` for details.  (On some systems, this function is emulated
    using :c:func:`fcntl`.)
 
-   If the :c:func:`flock` fails, an :exc:`OSError` exception is raised.
+   If the :c:func:`flock` call fails, an :exc:`OSError` exception is raised.
 
    .. audit-event:: fcntl.flock fd,operation fcntl.flock
 
@@ -176,17 +176,28 @@ The module defines the following functions:
    method are accepted as well) of the file to lock or unlock, and *cmd*
    is one of the following values:
 
-   * :const:`LOCK_UN` -- unlock
-   * :const:`LOCK_SH` -- acquire a shared lock
-   * :const:`LOCK_EX` -- acquire an exclusive lock
+   .. data:: LOCK_UN
 
-   When *cmd* is :const:`LOCK_SH` or :const:`LOCK_EX`, it can also be
-   bitwise ORed with :const:`LOCK_NB` to avoid blocking on lock acquisition.
-   If :const:`LOCK_NB` is used and the lock cannot be acquired, an
+      Release an existing lock.
+
+   .. data:: LOCK_SH
+
+      Acquire a shared lock.
+
+   .. data:: LOCK_EX
+
+      Acquire an exclusive lock.
+
+   .. data:: LOCK_NB
+
+      Bitwise OR with any of the other three ``LOCK_*`` constants to make
+      the request non-blocking.
+
+   If :const:`!LOCK_NB` is used and the lock cannot be acquired, an
    :exc:`OSError` will be raised and the exception will have an *errno*
-   attribute set to :const:`EACCES` or :const:`EAGAIN` (depending on the
+   attribute set to :const:`~errno.EACCES` or :const:`~errno.EAGAIN` (depending on the
    operating system; for portability, check for both values).  On at least some
-   systems, :const:`LOCK_EX` can only be used if the file descriptor refers to a
+   systems, :const:`!LOCK_EX` can only be used if the file descriptor refers to a
    file opened for writing.
 
    *len* is the number of bytes to lock, *start* is the byte offset at

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index 344b0c9b679df00e05c1c64ba843580e8ee7b556..18eac5ff406312087bdecdf63dd385ecc78b754c 100644 (file)
--- a/Doc/tools/.nitignore
+++ b/Doc/tools/.nitignore
@@ -29,7 +29,6 @@ Doc/library/email.parser.rst
 Doc/library/email.policy.rst
 Doc/library/exceptions.rst
 Doc/library/faulthandler.rst
-Doc/library/fcntl.rst
 Doc/library/functools.rst
 Doc/library/http.cookiejar.rst
 Doc/library/http.server.rst