bpo-11233: Create availability directive for documentation (GH-9692)

Replace "Availability: xxx" with ".. availability:: xxx" in the doc.
Original patch by Georg Brandl.

Co-Authored-By: Georg Brandl <georg@python.org>

1 files changed, 148 insertions, 157 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index bc8d5a8..75d473c 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -32,15 +32,6 @@ Notes on the availability of these functions:
   objects, and result in an object of the same type, if a path or file name is
   returned.
 
-* An "Availability: Unix" note means that this function is commonly found on
-  Unix systems.  It does not make any claims about its existence on a specific
-  operating system.
-
-* If not separately noted, all functions that claim "Availability: Unix" are
-  supported on Mac OS X, which builds on a Unix core.
-
-.. Availability notes get their own line and occur at the end of the function
-.. documentation.
 
 .. note::
 
@@ -105,7 +96,7 @@ process and user.
 
    Return the filename corresponding to the controlling terminal of the process.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: environ
@@ -235,7 +226,7 @@ process and user.
    and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
    would like to use a different encoding.
 
-   Availability: most flavors of Unix, Windows.
+   .. availability:: most flavors of Unix, Windows.
 
 
 .. function:: getenvb(key, default=None)
@@ -246,7 +237,7 @@ process and user.
    :func:`getenvb` is only available if :data:`supports_bytes_environ`
    is True.
 
-   Availability: most flavors of Unix.
+   .. availability:: most flavors of Unix.
 
    .. versionadded:: 3.2
 
@@ -267,7 +258,7 @@ process and user.
    Return the effective group id of the current process.  This corresponds to the
    "set id" bit on the file being executed in the current process.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: geteuid()
@@ -276,7 +267,7 @@ process and user.
 
    Return the current process's effective user id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: getgid()
@@ -285,7 +276,7 @@ process and user.
 
    Return the real group id of the current process.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: getgrouplist(user, group)
@@ -294,7 +285,7 @@ process and user.
    list, it is included; typically, *group* is specified as the group ID
    field from the password record for *user*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -303,7 +294,7 @@ process and user.
 
    Return list of supplemental group ids associated with the current process.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. note::
 
@@ -331,7 +322,7 @@ process and user.
    falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the
    current real user id.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. function:: getpgid(pid)
@@ -339,7 +330,7 @@ process and user.
    Return the process group id of the process with process id *pid*. If *pid* is 0,
    the process group id of the current process is returned.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 .. function:: getpgrp()
 
@@ -347,7 +338,7 @@ process and user.
 
    Return the id of the current process group.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: getpid()
@@ -365,7 +356,7 @@ process and user.
    the id returned is the one of the init process (1), on Windows it is still
    the same id, which may be already reused by another process.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added support for Windows.
@@ -383,7 +374,7 @@ process and user.
    (respectively) the calling process, the process group of the calling process,
    or the real user ID of the calling process.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -394,7 +385,7 @@ process and user.
 
    Parameters for the :func:`getpriority` and :func:`setpriority` functions.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -404,7 +395,7 @@ process and user.
    Return a tuple (ruid, euid, suid) denoting the current process's
    real, effective, and saved user ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.2
 
@@ -414,7 +405,7 @@ process and user.
    Return a tuple (rgid, egid, sgid) denoting the current process's
    real, effective, and saved group ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.2
 
@@ -425,7 +416,7 @@ process and user.
 
    Return the current process's real user id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: initgroups(username, gid)
@@ -434,7 +425,7 @@ process and user.
    the groups of which the specified username is a member, plus the specified
    group id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.2
 
@@ -447,7 +438,7 @@ process and user.
    changes to the environment affect subprocesses started with :func:`os.system`,
    :func:`popen` or :func:`fork` and :func:`execv`.
 
-   Availability: most flavors of Unix, Windows.
+   .. availability:: most flavors of Unix, Windows.
 
    .. note::
 
@@ -464,21 +455,21 @@ process and user.
 
    Set the current process's effective group id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: seteuid(euid)
 
    Set the current process's effective user id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setgid(gid)
 
    Set the current process' group id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setgroups(groups)
@@ -487,7 +478,7 @@ process and user.
    *groups*. *groups* must be a sequence, and each element must be an integer
    identifying a group. This operation is typically available only to the superuser.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. note:: On Mac OS X, the length of *groups* may not exceed the
       system-defined maximum number of effective group ids, typically 16.
@@ -499,7 +490,7 @@ process and user.
    Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
    which version is implemented (if any).  See the Unix manual for the semantics.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setpgid(pid, pgrp)
@@ -508,7 +499,7 @@ process and user.
    process with id *pid* to the process group with id *pgrp*.  See the Unix manual
    for the semantics.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setpriority(which, who, priority)
@@ -525,7 +516,7 @@ process and user.
    *priority* is a value in the range -20 to 19. The default priority is 0;
    lower priorities cause more favorable scheduling.
 
-   Availability: Unix
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -534,14 +525,14 @@ process and user.
 
    Set the current process's real and effective group ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setresgid(rgid, egid, sgid)
 
    Set the current process's real, effective, and saved group ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.2
 
@@ -550,7 +541,7 @@ process and user.
 
    Set the current process's real, effective, and saved user ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.2
 
@@ -559,21 +550,21 @@ process and user.
 
    Set the current process's real and effective user ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: getsid(pid)
 
    Call the system call :c:func:`getsid`.  See the Unix manual for the semantics.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setsid()
 
    Call the system call :c:func:`setsid`.  See the Unix manual for the semantics.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: setuid(uid)
@@ -582,7 +573,7 @@ process and user.
 
    Set the current process's user id.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. placed in this section since it relates to errno.... a little weak
@@ -631,7 +622,7 @@ process and user.
    :func:`socket.gethostname`  or even
    ``socket.gethostbyaddr(socket.gethostname())``.
 
-   Availability: recent flavors of Unix.
+   .. availability:: recent flavors of Unix.
 
    .. versionchanged:: 3.3
       Return type changed from a tuple to a tuple-like object
@@ -651,7 +642,7 @@ process and user.
    calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
    preferable to delete items of ``os.environ``.
 
-   Availability: most flavors of Unix, Windows.
+   .. availability:: most flavors of Unix, Windows.
 
 
 .. _os-newstreams:
@@ -754,7 +745,7 @@ as internal buffering of data.
    docs for :func:`chmod` for possible values of *mode*.  As of Python 3.3, this
    is equivalent to ``os.chmod(fd, mode)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: fchown(fd, uid, gid)
@@ -764,7 +755,7 @@ as internal buffering of data.
    :func:`chown`.  As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
    gid)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: fdatasync(fd)
@@ -772,7 +763,7 @@ as internal buffering of data.
    Force write of file with filedescriptor *fd* to disk. Does not force update of
    metadata.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. note::
       This function is not available on MacOS.
@@ -795,7 +786,7 @@ as internal buffering of data.
 
    As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: fstat(fd)
@@ -816,7 +807,7 @@ as internal buffering of data.
    file descriptor *fd*, like :func:`statvfs`.  As of Python 3.3, this is
    equivalent to ``os.statvfs(fd)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: fsync(fd)
@@ -828,7 +819,7 @@ as internal buffering of data.
    ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
    buffers associated with *f* are written to disk.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. function:: ftruncate(fd, length)
@@ -837,7 +828,7 @@ as internal buffering of data.
    most *length* bytes in size.  As of Python 3.3, this is equivalent to
    ``os.truncate(fd, length)``.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.5
       Added support for Windows
@@ -849,7 +840,7 @@ as internal buffering of data.
 
    See also :func:`set_blocking` and :meth:`socket.socket.setblocking`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.5
 
@@ -867,7 +858,7 @@ as internal buffering of data.
    :data:`F_ULOCK` or :data:`F_TEST`.
    *len* specifies the section of the file to lock.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -879,7 +870,7 @@ as internal buffering of data.
 
    Flags that specify what action :func:`lockf` will take.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1011,7 +1002,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
    portable approach, use the :mod:`pty` module.
 
-   Availability: some flavors of Unix.
+   .. availability:: some flavors of Unix.
 
    .. versionchanged:: 3.4
       The new file descriptors are now non-inheritable.
@@ -1023,7 +1014,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    reading and writing, respectively. The new file descriptor is
    :ref:`non-inheritable <fd_inheritance>`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.4
       The new file descriptors are now non-inheritable.
@@ -1037,7 +1028,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
    respectively.
 
-   Availability: some flavors of Unix.
+   .. availability:: some flavors of Unix.
 
    .. versionadded:: 3.3
 
@@ -1047,7 +1038,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Ensures that enough disk space is allocated for the file specified by *fd*
    starting from *offset* and continuing for *len* bytes.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1062,7 +1053,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
    :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1077,7 +1068,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Flags that can be used in *advice* in :func:`posix_fadvise` that specify
    the access pattern that is likely to be used.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1090,7 +1081,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return a bytestring containing the bytes read. If the end of the file
    referred to by *fd* has been reached, an empty bytes object is returned.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1116,8 +1107,8 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
    Combine the functionality of :func:`os.readv` and :func:`os.pread`.
 
-   Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
-   OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.
+   .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+      OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.
 
    .. versionadded:: 3.7
 
@@ -1132,7 +1123,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    If no bytes were read, it will return ``-1`` and set errno to
    :data:`errno.EAGAIN`.
 
-   Availability: Linux 4.14 and newer.
+   .. availability:: Linux 4.14 and newer.
 
    .. versionadded:: 3.7
 
@@ -1146,7 +1137,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Currently, on Linux, this feature is usable only on a file descriptor opened
    using the :data:`O_DIRECT` flag.
 
-   Availability: Linux 4.6 and newer.
+   .. availability:: Linux 4.6 and newer.
 
    .. versionadded:: 3.7
 
@@ -1158,7 +1149,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
    Return the number of bytes actually written.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1184,8 +1175,8 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
    Combine the functionality of :func:`os.writev` and :func:`os.pwrite`.
 
-   Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
-   OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.
+   .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+      OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.
 
    .. versionadded:: 3.7
 
@@ -1195,7 +1186,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This
    flag effect applies only to the data range written by the system call.
 
-   Availability: Linux 4.7 and newer.
+   .. availability:: Linux 4.7 and newer.
 
    .. versionadded:: 3.7
 
@@ -1205,7 +1196,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This
    flag effect applies only to the data range written by the system call.
 
-   Availability: Linux 4.7 and newer.
+   .. availability:: Linux 4.7 and newer.
 
    .. versionadded:: 3.7
 
@@ -1257,7 +1248,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Cross-platform applications should not use *headers*, *trailers* and *flags*
    arguments.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. note::
 
@@ -1274,7 +1265,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
 
    See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.5
 
@@ -1286,7 +1277,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Parameters to the :func:`sendfile` function, if the implementation supports
    them.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1304,7 +1295,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    The operating system may set a limit (:func:`sysconf` value
    ``'SC_IOV_MAX'``) on the number of buffers that can be used.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1314,7 +1305,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Return the process group associated with the terminal given by *fd* (an open
    file descriptor as returned by :func:`os.open`).
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: tcsetpgrp(fd, pg)
@@ -1322,7 +1313,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    Set the process group associated with the terminal given by *fd* (an open file
    descriptor as returned by :func:`os.open`) to *pg*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: ttyname(fd)
@@ -1331,7 +1322,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    file descriptor *fd*.  If *fd* is not associated with a terminal device, an
    exception is raised.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: write(fd, str)
@@ -1366,7 +1357,7 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    The operating system may set a limit (:func:`sysconf` value
    ``'SC_IOV_MAX'``) on the number of buffers that can be used.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1393,7 +1384,7 @@ Querying the size of a terminal
    should normally be used, ``os.get_terminal_size`` is the low-level
    implementation.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 .. class:: terminal_size
 
@@ -1442,13 +1433,13 @@ streams are closed, and inheritable handles are only inherited if the
 
    Get the "inheritable" flag of the specified handle (a boolean).
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 .. function:: set_handle_inheritable(handle, inheritable)
 
    Set the "inheritable" flag of the specified handle.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 
 .. _os-file-dir:
@@ -1603,7 +1594,7 @@ features:
 
    This function can support :ref:`not following symlinks <follow_symlinks>`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
       The *follow_symlinks* argument.
@@ -1668,7 +1659,7 @@ features:
    See :func:`shutil.chown` for a higher-level function that accepts names in
    addition to numeric ids.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
       Added support for specifying an open file descriptor for *path*,
@@ -1682,7 +1673,7 @@ features:
 
    Change the root directory of the current process to *path*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1694,7 +1685,7 @@ features:
    descriptor *fd*.  The descriptor must refer to an opened directory, not an
    open file.  As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: getcwd()
@@ -1713,7 +1704,7 @@ features:
    not follow symbolic links.  As of Python 3.3, this is equivalent to
    ``os.chflags(path, flags, follow_symlinks=False)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1726,7 +1717,7 @@ features:
    for possible values of *mode*.  As of Python 3.3, this is equivalent to
    ``os.chmod(path, mode, follow_symlinks=False)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1737,7 +1728,7 @@ features:
    function will not follow symbolic links.  As of Python 3.3, this is equivalent
    to ``os.chown(path, uid, gid, follow_symlinks=False)``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1751,7 +1742,7 @@ features:
    supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
    following symlinks <follow_symlinks>`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added Windows support.
@@ -1909,7 +1900,7 @@ features:
    FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
    doesn't open the FIFO --- it just creates the rendezvous point.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
       The *dir_fd* argument.
@@ -1931,7 +1922,7 @@ features:
    This function can also support :ref:`paths relative to directory descriptors
    <dir_fd>`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
       The *dir_fd* argument.
@@ -1975,7 +1966,7 @@ features:
    This function can support :ref:`specifying a file descriptor
    <path_fd>`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -1987,7 +1978,7 @@ features:
    the integer values defined for those names by the host operating system.  This
    can be used to determine the set of names known to the system.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: readlink(path, *, dir_fd=None)
@@ -2005,7 +1996,7 @@ features:
    This function can also support :ref:`paths relative to directory descriptors
    <dir_fd>`.
 
-   Availability: Unix, Windows
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
@@ -2596,7 +2587,7 @@ features:
 
    This function can support :ref:`specifying a file descriptor <path_fd>`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionchanged:: 3.2
       The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
@@ -2726,7 +2717,7 @@ features:
       :exc:`OSError` is raised when the function is called by an unprivileged
       user.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
@@ -2743,7 +2734,7 @@ features:
 
    Force write of everything to disk.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -2755,7 +2746,7 @@ features:
 
    This function can support :ref:`specifying a file descriptor <path_fd>`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionadded:: 3.3
 
@@ -2962,7 +2953,7 @@ features:
           for name in dirs:
               os.rmdir(name, dir_fd=rootfd)
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -3139,7 +3130,7 @@ to be ignored.
    you can check whether or not it is available using :data:`os.supports_fd`.
    If it is unavailable, using it will raise a :exc:`NotImplementedError`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionadded:: 3.3
       Added support for specifying an open file descriptor for *path*
@@ -3173,7 +3164,7 @@ written in Python, such as a mail server's external command delivery program.
 
    Exit code that means no error occurred.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_USAGE
@@ -3181,49 +3172,49 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means the command was used incorrectly, such as when the wrong
    number of arguments are given.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_DATAERR
 
    Exit code that means the input data was incorrect.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_NOINPUT
 
    Exit code that means an input file did not exist or was not readable.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_NOUSER
 
    Exit code that means a specified user did not exist.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_NOHOST
 
    Exit code that means a specified host did not exist.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_UNAVAILABLE
 
    Exit code that means that a required service is unavailable.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_SOFTWARE
 
    Exit code that means an internal software error was detected.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_OSERR
@@ -3231,7 +3222,7 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means an operating system error was detected, such as the
    inability to fork or create a pipe.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_OSFILE
@@ -3239,21 +3230,21 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means some system file did not exist, could not be opened, or had
    some other kind of error.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_CANTCREAT
 
    Exit code that means a user specified output file could not be created.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_IOERR
 
    Exit code that means that an error occurred while doing I/O on some file.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_TEMPFAIL
@@ -3262,7 +3253,7 @@ written in Python, such as a mail server's external command delivery program.
    that may not really be an error, such as a network connection that couldn't be
    made during a retryable operation.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_PROTOCOL
@@ -3270,7 +3261,7 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means that a protocol exchange was illegal, invalid, or not
    understood.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_NOPERM
@@ -3278,21 +3269,21 @@ written in Python, such as a mail server's external command delivery program.
    Exit code that means that there were insufficient permissions to perform the
    operation (but not intended for file system problems).
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_CONFIG
 
    Exit code that means that some kind of configuration error occurred.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: EX_NOTFOUND
 
    Exit code that means something like "an entry was not found".
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: fork()
@@ -3307,7 +3298,7 @@ written in Python, such as a mail server's external command delivery program.
 
       See :mod:`ssl` for applications that use the SSL module with fork().
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: forkpty()
@@ -3318,7 +3309,7 @@ written in Python, such as a mail server's external command delivery program.
    master end of the pseudo-terminal.  For a more portable approach, use the
    :mod:`pty` module.  If an error occurs :exc:`OSError` is raised.
 
-   Availability: some flavors of Unix.
+   .. availability:: some flavors of Unix.
 
 
 .. function:: kill(pid, sig)
@@ -3352,14 +3343,14 @@ written in Python, such as a mail server's external command delivery program.
 
    Send the signal *sig* to the process group *pgid*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: nice(increment)
 
    Add *increment* to the process's "niceness".  Return the new niceness.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: plock(op)
@@ -3367,7 +3358,7 @@ written in Python, such as a mail server's external command delivery program.
    Lock program segments into memory.  The value of *op* (defined in
    ``<sys/lock.h>``) determines which segments are locked.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: popen(cmd, mode='r', buffering=-1)
@@ -3496,7 +3487,7 @@ written in Python, such as a mail server's external command delivery program.
 
    There is no way to unregister a function.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -3560,10 +3551,10 @@ written in Python, such as a mail server's external command delivery program.
       L = ['cp', 'index.html', '/dev/null']
       os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
 
-   Availability: Unix, Windows.  :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
-   and :func:`spawnvpe` are not available on Windows.  :func:`spawnle` and
-   :func:`spawnve` are not thread-safe on Windows; we advise you to use the
-   :mod:`subprocess` module instead.
+   .. availability:: Unix, Windows.  :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
+      and :func:`spawnvpe` are not available on Windows.  :func:`spawnle` and
+      :func:`spawnve` are not thread-safe on Windows; we advise you to use the
+      :mod:`subprocess` module instead.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -3577,7 +3568,7 @@ written in Python, such as a mail server's external command delivery program.
    will return as soon as the new process has been created, with the process id as
    the return value.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. data:: P_WAIT
@@ -3588,7 +3579,7 @@ written in Python, such as a mail server's external command delivery program.
    of the process the run is successful, or ``-signal`` if a signal kills the
    process.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. data:: P_DETACH
@@ -3600,7 +3591,7 @@ written in Python, such as a mail server's external command delivery program.
    console of the calling process. If :const:`P_OVERLAY` is used, the current
    process will be replaced; the :func:`spawn\* <spawnl>` function will not return.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 
 .. function:: startfile(path[, operation])
@@ -3629,7 +3620,7 @@ written in Python, such as a mail server's external command delivery program.
    function is not resolved until this function is first called.  If the function
    cannot be resolved, :exc:`NotImplementedError` will be raised.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 
 .. function:: system(command)
@@ -3656,7 +3647,7 @@ written in Python, such as a mail server's external command delivery program.
    to using this function.  See the :ref:`subprocess-replacements` section in
    the :mod:`subprocess` documentation for some helpful recipes.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. function:: times()
@@ -3679,7 +3670,7 @@ written in Python, such as a mail server's external command delivery program.
    On Windows, only :attr:`user` and :attr:`system` are known; the other
    attributes are zero.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.3
       Return type changed from a tuple to a tuple-like object
@@ -3694,7 +3685,7 @@ written in Python, such as a mail server's external command delivery program.
    number is zero); the high bit of the low byte is set if a core file was
    produced.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 .. function:: waitid(idtype, id, options)
 
@@ -3709,7 +3700,7 @@ written in Python, such as a mail server's external command delivery program.
    :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
    children in a waitable state.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -3720,7 +3711,7 @@ written in Python, such as a mail server's external command delivery program.
    These are the possible values for *idtype* in :func:`waitid`. They affect
    how *id* is interpreted.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -3731,7 +3722,7 @@ written in Python, such as a mail server's external command delivery program.
    Flags that can be used in *options* in :func:`waitid` that specify what
    child signal to wait for.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -3744,7 +3735,7 @@ written in Python, such as a mail server's external command delivery program.
    These are the possible values for :attr:`si_code` in the result returned by
    :func:`waitid`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -3791,7 +3782,7 @@ written in Python, such as a mail server's external command delivery program.
    option argument is the same as that provided to :func:`waitpid` and
    :func:`wait4`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: wait4(pid, options)
@@ -3802,7 +3793,7 @@ written in Python, such as a mail server's external command delivery program.
    resource usage information.  The arguments to :func:`wait4` are the same
    as those provided to :func:`waitpid`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: WNOHANG
@@ -3810,7 +3801,7 @@ written in Python, such as a mail server's external command delivery program.
    The option for :func:`waitpid` to return immediately if no child process status
    is available immediately. The function returns ``(0, 0)`` in this case.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: WCONTINUED
@@ -3818,7 +3809,7 @@ written in Python, such as a mail server's external command delivery program.
    This option causes child processes to be reported if they have been continued
    from a job control stop since their status was last reported.
 
-   Availability: some Unix systems.
+   .. availability:: some Unix systems.
 
 
 .. data:: WUNTRACED
@@ -3826,7 +3817,7 @@ written in Python, such as a mail server's external command delivery program.
    This option causes child processes to be reported if they have been stopped but
    their current state has not been reported since they were stopped.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 The following functions take a process status code as returned by
@@ -3838,7 +3829,7 @@ used to determine the disposition of a process.
    Return ``True`` if a core dump was generated for the process, otherwise
    return ``False``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WIFCONTINUED(status)
@@ -3846,7 +3837,7 @@ used to determine the disposition of a process.
    Return ``True`` if the process has been continued from a job control stop,
    otherwise return ``False``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WIFSTOPPED(status)
@@ -3854,7 +3845,7 @@ used to determine the disposition of a process.
    Return ``True`` if the process has been stopped, otherwise return
    ``False``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WIFSIGNALED(status)
@@ -3862,7 +3853,7 @@ used to determine the disposition of a process.
    Return ``True`` if the process exited due to a signal, otherwise return
    ``False``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WIFEXITED(status)
@@ -3870,7 +3861,7 @@ used to determine the disposition of a process.
    Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
    otherwise return ``False``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WEXITSTATUS(status)
@@ -3878,21 +3869,21 @@ used to determine the disposition of a process.
    If ``WIFEXITED(status)`` is true, return the integer parameter to the
    :manpage:`exit(2)` system call.  Otherwise, the return value is meaningless.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WSTOPSIG(status)
 
    Return the signal which caused the process to stop.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: WTERMSIG(status)
 
    Return the signal which caused the process to exit.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 Interface to the scheduler
@@ -4038,7 +4029,7 @@ Miscellaneous System Information
    included in ``confstr_names``, an :exc:`OSError` is raised with
    :const:`errno.EINVAL` for the error number.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: confstr_names
@@ -4047,7 +4038,7 @@ Miscellaneous System Information
    defined for those names by the host operating system. This can be used to
    determine the set of names known to the system.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: cpu_count()
@@ -4068,7 +4059,7 @@ Miscellaneous System Information
    1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
    unobtainable.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. function:: sysconf(name)
@@ -4078,7 +4069,7 @@ Miscellaneous System Information
    the *name* parameter for :func:`confstr` apply here as well; the dictionary that
    provides information on the known names is given by ``sysconf_names``.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 
 .. data:: sysconf_names
@@ -4087,7 +4078,7 @@ Miscellaneous System Information
    defined for those names by the host operating system. This can be used to
    determine the set of names known to the system.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 The following data values are used to support path manipulation operations.  These
 are defined for all platforms.
@@ -4199,7 +4190,7 @@ Random numbers
    See also the `Linux getrandom() manual page
    <http://man7.org/linux/man-pages/man2/getrandom.2.html>`_.
 
-   Availability: Linux 3.17 and newer.
+   .. availability:: Linux 3.17 and newer.
 
    .. versionadded:: 3.6