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>

Doc/c-api/exceptions.rst

@@ -186,34 +186,42 @@ NULL pointer for use in a ``return`` statement.
    then it constructs a tuple object whose first item is the *ierr* value and whose
    second item is the corresponding error message (gotten from
    :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError,
-   object)``. This function always returns *NULL*. Availability: Windows.
+   object)``. This function always returns *NULL*.
+
+   .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)
 
    Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter
-   specifying the exception type to be raised. Availability: Windows.
+   specifying the exception type to be raised.
+
+   .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
    filename is given as a C string.  *filename* is decoded from the filesystem
-   encoding (:func:`os.fsdecode`).  Availability: Windows.
+   encoding (:func:`os.fsdecode`).
+
+   .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
    additional parameter specifying the exception type to be raised.
-   Availability: Windows.
+
+   .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)
 
    Similar to :c:func:`PyErr_SetExcFromWindowsErrWithFilenameObject`,
    but accepts a second filename object.
-   Availability: Windows.
+
+   .. availability:: Windows.
 
    .. versionadded:: 3.4
 
@@ -221,7 +229,9 @@ NULL pointer for use in a ``return`` statement.
 .. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
-   parameter specifying the exception type to be raised. Availability: Windows.
+   parameter specifying the exception type to be raised.
+
+   .. availability:: Windows.
 
 
 .. c:function:: PyObject* PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)

Doc/c-api/init.rst

@@ -156,7 +156,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    See :pep:`529` for more details.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 .. c:var:: Py_LegacyWindowsStdioFlag
 
@@ -168,7 +168,7 @@ to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to 2.
 
    See :pep:`528` for more details.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 .. c:var:: Py_NoSiteFlag
 

Doc/library/_thread.rst

@@ -101,7 +101,8 @@ This module defines the following constants and functions:
    memory page size - platform documentation should be referred to for more
    information (4 KiB pages are common; using multiples of 4096 for the stack size is
    the suggested approach in the absence of more specific information).
-   Availability: Windows, systems with POSIX threads.
+
+   .. availability:: Windows, systems with POSIX threads.
 
 
 .. data:: TIMEOUT_MAX

Doc/library/asyncio-eventloop.rst

@@ -510,7 +510,7 @@ Opening network connections
    See the documentation of the :meth:`loop.create_connection` method
    for information about arguments to this method.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -630,7 +630,7 @@ Creating network servers
    See the documentation of the :meth:`loop.create_server` method
    for information about arguments to this method.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -979,7 +979,7 @@ Unix signals
    Return ``True`` if the signal handler was removed, or ``False`` if
    no handler was set for the given signal.
 
-Availability: Unix.
+   .. availability:: Unix.
 
 .. seealso::
 
@@ -1423,14 +1423,14 @@ on all platforms.
       asyncio.set_event_loop(loop)
 
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 
 .. class:: ProactorEventLoop
 
    An event loop for Windows that uses "I/O Completion Ports" (IOCP).
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. seealso::
 

Doc/library/asyncio-policy.rst

@@ -107,7 +107,7 @@ asyncio ships with the following built-in policies:
    An alternative event loop policy that uses the
    :class:`SelectorEventLoop` event loop implementation.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 
 .. class:: WindowsProactorEventLoopPolicy
@@ -115,7 +115,7 @@ asyncio ships with the following built-in policies:
    An alternative event loop policy that uses the
    :class:`ProactorEventLoop` event loop implementation.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
 
 Process Watchers

Doc/library/asyncio-stream.rst

@@ -114,7 +114,7 @@ and work with streams:
 
    See also the documentation of :meth:`loop.create_unix_connection`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -136,7 +136,7 @@ and work with streams:
 
    See also the documentation of :meth:`loop.create_unix_server`.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 

Doc/library/asyncore.rst

@@ -273,14 +273,18 @@ any that have been added to the map during asynchronous service) is closed.
    with an optional map argument and wraps it for use with the :c:func:`poll`
    or :c:func:`loop` functions.  If provided a file object or anything with a
    :c:func:`fileno` method, that method will be called and passed to the
-   :class:`file_wrapper` constructor.  Availability: UNIX.
+   :class:`file_wrapper` constructor.
+
+   .. availability:: Unix.
 
 .. class:: file_wrapper()
 
    A file_wrapper takes an integer file descriptor and calls :func:`os.dup` to
    duplicate the handle so that the original handle may be closed independently
    of the file_wrapper.  This class implements sufficient methods to emulate a
-   socket for use by the :class:`file_dispatcher` class.  Availability: UNIX.
+   socket for use by the :class:`file_dispatcher` class.
+
+   .. availability:: Unix.
 
 
 .. _asyncore-example-1:

Doc/library/codecs.rst

@@ -1471,7 +1471,7 @@ functions can be used directly if desired.
 
 Encode operand according to the ANSI codepage (CP_ACP).
 
-Availability: Windows only.
+.. availability:: Windows only.
 
 .. versionchanged:: 3.3
    Support any error handler.

Doc/library/hashlib.rst

@@ -271,7 +271,7 @@ include a `salt <https://en.wikipedia.org/wiki/Salt_%28cryptography%29>`_.
    factor and *maxmem* limits memory (OpenSSL 1.1.0 defaults to 32 MiB).
    *dklen* is the length of the derived key.
 
-   Availability: OpenSSL 1.1+
+   .. availability:: OpenSSL 1.1+.
 
    .. versionadded:: 3.6
 

Doc/library/intro.rst

@@ -47,3 +47,16 @@ this material.
 
 Let the show begin!
 
+
+.. _availability:
+
+Notes on availability
+=====================
+
+* 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.
+

Doc/library/mimetypes.rst

@@ -260,7 +260,9 @@ than one MIME-type database; it provides an interface similar to the one of the
 
    .. method:: MimeTypes.read_windows_registry(strict=True)
 
-      Load MIME type information from the Windows registry.  Availability: Windows.
+      Load MIME type information from the Windows registry.
+
+      .. availability:: Windows.
 
       If *strict* is ``True``, information will be added to the list of standard
       types, else to the list of non-standard types.

Doc/library/os.path.rst

@@ -93,7 +93,7 @@ the :mod:`glob` module.)
    pathnames, or if *paths* is empty.  Unlike :func:`commonprefix`, this
    returns a valid path.
 
-   Availability: Unix, Windows
+   .. availability:: Unix, Windows.
 
    .. versionadded:: 3.5
 
@@ -357,7 +357,7 @@ the :mod:`glob` module.)
 
    *start* defaults to :attr:`os.curdir`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.
@@ -369,7 +369,7 @@ the :mod:`glob` module.)
    This is determined by the device number and i-node number and raises an
    exception if an :func:`os.stat` call on either pathname fails.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added Windows support.
@@ -385,7 +385,7 @@ the :mod:`glob` module.)
 
    Return ``True`` if the file descriptors *fp1* and *fp2* refer to the same file.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.2
       Added Windows support.
@@ -401,7 +401,7 @@ the :mod:`glob` module.)
    :func:`os.lstat`, or :func:`os.stat`.  This function implements the
    underlying comparison used by :func:`samefile` and :func:`sameopenfile`.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
    .. versionchanged:: 3.4
       Added Windows support.

Doc/library/resource.rst

@@ -92,7 +92,7 @@ this module for those platforms.
    :exc:`PermissionError` when the user doesn't have ``CAP_SYS_RESOURCE`` for
    the process.
 
-   Availability: Linux 2.6.36 or later with glibc 2.13 or later
+   .. availability:: Linux 2.6.36 or later with glibc 2.13 or later.
 
    .. versionadded:: 3.4
 
@@ -178,7 +178,7 @@ platform.
 
    The number of bytes that can be allocated for POSIX message queues.
 
-   Availability: Linux 2.6.8 or later.
+   .. availability:: Linux 2.6.8 or later.
 
    .. versionadded:: 3.4
 
@@ -187,7 +187,7 @@ platform.
 
    The ceiling for the process's nice level (calculated as 20 - rlim_cur).
 
-   Availability: Linux 2.6.12 or later.
+   .. availability:: Linux 2.6.12 or later.
 
    .. versionadded:: 3.4
 
@@ -196,7 +196,7 @@ platform.
 
    The ceiling of the real-time priority.
 
-   Availability: Linux 2.6.12 or later.
+   .. availability:: Linux 2.6.12 or later.
 
    .. versionadded:: 3.4
 
@@ -206,7 +206,7 @@ platform.
    The time limit (in microseconds) on CPU time that a process can spend
    under real-time scheduling without making a blocking syscall.
 
-   Availability: Linux 2.6.25 or later.
+   .. availability:: Linux 2.6.25 or later.
 
    .. versionadded:: 3.4
 
@@ -215,7 +215,7 @@ platform.
 
    The number of signals which the process may queue.
 
-   Availability: Linux 2.6.8 or later.
+   .. availability:: Linux 2.6.8 or later.
 
    .. versionadded:: 3.4
 
@@ -225,7 +225,7 @@ platform.
    This limits the amount of network memory, and hence the amount of mbufs,
    that this user may hold at any time.
 
-   Availability: FreeBSD 9 or later.
+   .. availability:: FreeBSD 9 or later.
 
    .. versionadded:: 3.4
 
@@ -236,7 +236,7 @@ platform.
    This limit is enforced only if bit 1 of the vm.overcommit sysctl is set.
    Please see :manpage:`tuning(7)` for a complete description of this sysctl.
 
-   Availability: FreeBSD 9 or later.
+   .. availability:: FreeBSD 9 or later.
 
    .. versionadded:: 3.4
 
@@ -244,7 +244,7 @@ platform.
 
    The maximum number of pseudo-terminals created by this user id.
 
-   Availability: FreeBSD 9 or later.
+   .. availability:: FreeBSD 9 or later.
 
    .. versionadded:: 3.4
 

Doc/library/select.rst

@@ -171,7 +171,9 @@ The module defines the following:
    :func:`poll` or another interface in this module.  This doesn't apply
    to other kind of file-like objects such as sockets.
 
-   This value is guaranteed by POSIX to be at least 512.  Availability: Unix.
+   This value is guaranteed by POSIX to be at least 512.
+
+   .. availability:: Unix
 
    .. versionadded:: 3.2
 

Doc/library/shutil.rst

@@ -351,7 +351,7 @@ Directory and files operations
    .. versionchanged:: 3.8
      On Windows, *path* can now be a file or directory.
 
-   Availability: Unix, Windows.
+   .. availability:: Unix, Windows.
 
 .. function:: chown(path, user=None, group=None)
 
@@ -362,7 +362,7 @@ Directory and files operations
 
    See also :func:`os.chown`, the underlying function.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 

Doc/library/signal.rst

@@ -106,7 +106,7 @@ The variables defined in the :mod:`signal` module are:
    The signal corresponding to the :kbd:`Ctrl+C` keystroke event. This signal can
    only be used with :func:`os.kill`.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.2
 
@@ -116,7 +116,7 @@ The variables defined in the :mod:`signal` module are:
    The signal corresponding to the :kbd:`Ctrl+Break` keystroke event. This signal can
    only be used with :func:`os.kill`.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.2
 
@@ -193,7 +193,9 @@ The :mod:`signal` module defines the following functions:
    then the number of seconds before any previously set alarm was to have been
    delivered. If *time* is zero, no alarm is scheduled, and any scheduled alarm is
    canceled.  If the return value is zero, no alarm is currently scheduled.  (See
-   the Unix man page :manpage:`alarm(2)`.) Availability: Unix.
+   the Unix man page :manpage:`alarm(2)`.)
+
+   .. availability:: Unix.
 
 
 .. function:: getsignal(signalnum)
@@ -252,8 +254,8 @@ The :mod:`signal` module defines the following functions:
    If *signalnum* is 0, then no signal is sent, but error checking is still
    performed; this can be used to check if the target thread is still running.
 
-   Availability: Unix (see the man page :manpage:`pthread_kill(3)` for further
-   information).
+   .. availability:: Unix (see the man page :manpage:`pthread_kill(3)` for further
+      information).
 
    See also :func:`os.kill`.
 
@@ -283,8 +285,8 @@ The :mod:`signal` module defines the following functions:
    For example, ``signal.pthread_sigmask(signal.SIG_BLOCK, [])`` reads the
    signal mask of the calling thread.
 
-   Availability: Unix. See the man page :manpage:`sigprocmask(3)` and
-   :manpage:`pthread_sigmask(3)` for further information.
+   .. availability:: Unix. See the man page :manpage:`sigprocmask(3)` and
+      :manpage:`pthread_sigmask(3)` for further information.
 
    See also :func:`pause`, :func:`sigpending` and :func:`sigwait`.
 
@@ -309,13 +311,16 @@ The :mod:`signal` module defines the following functions:
    The old values are returned as a tuple: (delay, interval).
 
    Attempting to pass an invalid interval timer will cause an
-   :exc:`ItimerError`.  Availability: Unix.
+   :exc:`ItimerError`.
+
+   .. availability:: Unix.
 
 
 .. function:: getitimer(which)
 
    Returns current value of a given interval timer specified by *which*.
-   Availability: Unix.
+
+   .. availability:: Unix.
 
 
 .. function:: set_wakeup_fd(fd, *, warn_on_full_buffer=True)
@@ -365,8 +370,10 @@ The :mod:`signal` module defines the following functions:
 
    Change system call restart behaviour: if *flag* is :const:`False`, system
    calls will be restarted when interrupted by signal *signalnum*, otherwise
-   system calls will be interrupted.  Returns nothing.  Availability: Unix (see
-   the man page :manpage:`siginterrupt(3)` for further information).
+   system calls will be interrupted.  Returns nothing.
+
+   .. availability:: Unix (see the man page :manpage:`siginterrupt(3)`
+      for further information).
 
    Note that installing a signal handler with :func:`signal` will reset the
    restart behaviour to interruptible by implicitly calling
@@ -405,8 +412,8 @@ The :mod:`signal` module defines the following functions:
    thread (i.e., the signals which have been raised while blocked).  Return the
    set of the pending signals.
 
-   Availability: Unix (see the man page :manpage:`sigpending(2)` for further
-   information).
+   .. availability:: Unix (see the man page :manpage:`sigpending(2)` for further
+      information).
 
    See also :func:`pause`, :func:`pthread_sigmask` and :func:`sigwait`.
 
@@ -419,8 +426,8 @@ The :mod:`signal` module defines the following functions:
    signals specified in the signal set *sigset*.  The function accepts the signal
    (removes it from the pending list of signals), and returns the signal number.
 
-   Availability: Unix (see the man page :manpage:`sigwait(3)` for further
-   information).
+   .. availability:: Unix (see the man page :manpage:`sigwait(3)` for further
+      information).
 
    See also :func:`pause`, :func:`pthread_sigmask`, :func:`sigpending`,
    :func:`sigwaitinfo` and :func:`sigtimedwait`.
@@ -444,8 +451,8 @@ The :mod:`signal` module defines the following functions:
    :attr:`si_errno`, :attr:`si_pid`, :attr:`si_uid`, :attr:`si_status`,
    :attr:`si_band`.
 
-   Availability: Unix (see the man page :manpage:`sigwaitinfo(2)` for further
-   information).
+   .. availability:: Unix (see the man page :manpage:`sigwaitinfo(2)` for further
+      information).
 
    See also :func:`pause`, :func:`sigwait` and :func:`sigtimedwait`.
 
@@ -463,8 +470,8 @@ The :mod:`signal` module defines the following functions:
    specifying a timeout. If *timeout* is specified as :const:`0`, a poll is
    performed. Returns :const:`None` if a timeout occurs.
 
-   Availability: Unix (see the man page :manpage:`sigtimedwait(2)` for further
-   information).
+   .. availability:: Unix (see the man page :manpage:`sigtimedwait(2)` for further
+      information).
 
    See also :func:`pause`, :func:`sigwait` and :func:`sigwaitinfo`.
 

Doc/library/socket.rst

@@ -161,7 +161,7 @@ created.  Socket addresses are represented as follows:
 
   - *feat* and *mask* are unsigned 32bit integers.
 
-  Availability Linux 2.6.38, some algorithm types require more recent Kernels.
+  .. availability:: Linux 2.6.38, some algorithm types require more recent Kernels.
 
   .. versionadded:: 3.6
 
@@ -169,7 +169,7 @@ created.  Socket addresses are represented as follows:
   their hosts. The sockets are represented as a ``(CID, port)`` tuple
   where the context ID or CID and port are integers.
 
-  Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5
+  .. availability:: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.
 
   .. versionadded:: 3.7
 
@@ -313,7 +313,7 @@ Constants
       `Secure File Descriptor Handling <http://udrepper.livejournal.com/20407.html>`_
       for a more thorough explanation.
 
-   Availability: Linux >= 2.6.27.
+   .. availability:: Linux >= 2.6.27.
 
    .. versionadded:: 3.2
 
@@ -361,7 +361,7 @@ Constants
    Many constants of these forms, documented in the Linux documentation, are
    also defined in the socket module.
 
-   Availability: Linux >= 2.6.25.
+   .. availability:: Linux >= 2.6.25.
 
    .. versionadded:: 3.3
 
@@ -372,7 +372,7 @@ Constants
    Broadcast manager constants, documented in the Linux documentation, are also
    defined in the socket module.
 
-   Availability: Linux >= 2.6.25.
+   .. availability:: Linux >= 2.6.25.
 
    .. versionadded:: 3.4
 
@@ -384,7 +384,7 @@ Constants
 
    This constant is documented in the Linux documentation.
 
-   Availability: Linux >= 3.6.
+   .. availability:: Linux >= 3.6.
 
    .. versionadded:: 3.5
 
@@ -393,7 +393,7 @@ Constants
    CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2) protocol.
    ISO-TP constants, documented in the Linux documentation.
 
-   Availability: Linux >= 2.6.25
+   .. availability:: Linux >= 2.6.25.
 
    .. versionadded:: 3.7
 
@@ -405,7 +405,7 @@ Constants
    Many constants of these forms, documented in the Linux documentation, are
    also defined in the socket module.
 
-   Availability: Linux >= 2.2.
+   .. availability:: Linux >= 2.2.
 
 
 .. data:: AF_RDS
@@ -416,7 +416,7 @@ Constants
    Many constants of these forms, documented in the Linux documentation, are
    also defined in the socket module.
 
-   Availability: Linux >= 2.6.30.
+   .. availability:: Linux >= 2.6.30.
 
    .. versionadded:: 3.3
 
@@ -444,7 +444,7 @@ Constants
 
    Constants for Linux Kernel cryptography.
 
-   Availability: Linux >= 2.6.38.
+   .. availability:: Linux >= 2.6.38.
 
    .. versionadded:: 3.6
 
@@ -456,13 +456,13 @@ Constants
 
    Constants for Linux host/guest communication.
 
-   Availability: Linux >= 4.8.
+   .. availability:: Linux >= 4.8.
 
    .. versionadded:: 3.7
 
 .. data:: AF_LINK
 
-  Availability: BSD, OSX.
+  .. availability:: BSD, OSX.
 
   .. versionadded:: 3.4
 
@@ -493,7 +493,7 @@ Constants
    Constant for Qualcomm's IPC router protocol, used to communicate with
    service providing remote processors.
 
-   Availability: Linux >= 4.7.
+   .. availability:: Linux >= 4.7.
 
 Functions
 ^^^^^^^^^
@@ -618,7 +618,7 @@ The following functions all create :ref:`socket objects <socket-objects>`.
    Instantiate a socket from data obtained from the :meth:`socket.share`
    method.  The socket is assumed to be in blocking mode.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.3
 
@@ -865,7 +865,7 @@ The :mod:`socket` module also offers various network-related services:
    both the value of *address_family* and the underlying implementation of
    :c:func:`inet_pton`.
 
-   Availability: Unix (maybe not all platforms), Windows.
+   .. availability:: Unix (maybe not all platforms), Windows.
 
    .. versionchanged:: 3.4
       Windows support added
@@ -885,7 +885,7 @@ The :mod:`socket` module also offers various network-related services:
    length for the specified address family, :exc:`ValueError` will be raised.
    :exc:`OSError` is raised for errors from the call to :func:`inet_ntop`.
 
-   Availability: Unix (maybe not all platforms), Windows.
+   .. availability:: Unix (maybe not all platforms), Windows.
 
    .. versionchanged:: 3.4
       Windows support added
@@ -911,7 +911,7 @@ The :mod:`socket` module also offers various network-related services:
    buffer.  Raises :exc:`OverflowError` if *length* is outside the
    permissible range of values.
 
-   Availability: most Unix platforms, possibly others.
+   .. availability:: most Unix platforms, possibly others.
 
    .. versionadded:: 3.3
 
@@ -932,7 +932,7 @@ The :mod:`socket` module also offers various network-related services:
    amount of ancillary data that can be received, since additional
    data may be able to fit into the padding area.
 
-   Availability: most Unix platforms, possibly others.
+   .. availability:: most Unix platforms, possibly others.
 
    .. versionadded:: 3.3
 
@@ -957,7 +957,7 @@ The :mod:`socket` module also offers various network-related services:
    Set the machine's hostname to *name*.  This will raise an
    :exc:`OSError` if you don't have enough rights.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -968,7 +968,7 @@ The :mod:`socket` module also offers various network-related services:
    (index int, name string) tuples.
    :exc:`OSError` if the system call fails.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -979,7 +979,7 @@ The :mod:`socket` module also offers various network-related services:
    interface name.
    :exc:`OSError` if no interface with the given name exists.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -990,7 +990,7 @@ The :mod:`socket` module also offers various network-related services:
    interface index number.
    :exc:`OSError` if no interface with the given index exists.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -1317,7 +1317,7 @@ to sockets.
                   fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
           return msg, list(fds)
 
-   Availability: most Unix platforms, possibly others.
+   .. availability:: most Unix platforms, possibly others.
 
    .. versionadded:: 3.3
 
@@ -1359,7 +1359,7 @@ to sockets.
       >>> [b1, b2, b3]
       [bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]
 
-   Availability: most Unix platforms, possibly others.
+   .. availability:: most Unix platforms, possibly others.
 
    .. versionadded:: 3.3
 
@@ -1463,7 +1463,7 @@ to sockets.
       def send_fds(sock, msg, fds):
           return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])
 
-   Availability: most Unix platforms, possibly others.
+   .. availability:: most Unix platforms, possibly others.
 
    .. versionadded:: 3.3
 
@@ -1477,7 +1477,7 @@ to sockets.
    Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
    Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socket.
 
-   Availability: Linux >= 2.6.38
+   .. availability:: Linux >= 2.6.38.
 
    .. versionadded:: 3.6
 
@@ -1578,7 +1578,7 @@ to sockets.
    Once this method has been called, it is safe to close the socket since
    the operating system has already duplicated it for the target process.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.3
 

Doc/library/ssl.rst

@@ -328,7 +328,7 @@ Random generation
    See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources
    of entropy-gathering daemons.
 
-   Availability: not available with LibreSSL and OpenSSL > 1.1.0
+   .. availability:: not available with LibreSSL and OpenSSL > 1.1.0.
 
 .. function:: RAND_add(bytes, entropy)
 
@@ -460,8 +460,8 @@ Certificate handling
    * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath,
    * :attr:`openssl_capath` - hard coded path to a capath directory
 
-   Availability: LibreSSL ignores the environment vars
-   :attr:`openssl_cafile_env` and :attr:`openssl_capath_env`
+   .. availability:: LibreSSL ignores the environment vars
+     :attr:`openssl_cafile_env` and :attr:`openssl_capath_env`.
 
    .. versionadded:: 3.4
 
@@ -484,7 +484,7 @@ Certificate handling
       [(b'data...', 'x509_asn', {'1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2'}),
        (b'data...', 'x509_asn', True)]
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.4
 
@@ -499,7 +499,7 @@ Certificate handling
    :const:`x509_asn` for X.509 ASN.1 data or :const:`pkcs_7_asn` for
    PKCS#7 ASN.1 data.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionadded:: 3.4
 
@@ -1610,7 +1610,7 @@ to speed up repeated connections from the same clients.
          'strength_bits': 128,
          'symmetric': 'aes-128-gcm'}]
 
-   Availability: OpenSSL 1.0.2+
+   .. availability:: OpenSSL 1.0.2+.
 
    .. versionadded:: 3.6
 

Doc/library/subprocess.rst

@@ -1330,7 +1330,7 @@ handling consistency are valid for these functions.
       >>> subprocess.getstatusoutput('/bin/kill $$')
       (-15, '')
 
-   Availability: POSIX & Windows
+   .. availability:: POSIX & Windows.
 
    .. versionchanged:: 3.3.4
       Windows support was added.
@@ -1350,7 +1350,7 @@ handling consistency are valid for these functions.
       >>> subprocess.getoutput('ls /bin/ls')
       '/bin/ls'
 
-   Availability: POSIX & Windows
+   .. availability:: POSIX & Windows.
 
    .. versionchanged:: 3.3.4
       Windows support added

Doc/library/sys.rst

@@ -161,7 +161,9 @@ always available.
 
 .. data:: dllhandle
 
-   Integer specifying the handle of the Python DLL. Availability: Windows.
+   Integer specifying the handle of the Python DLL.
+
+   .. availability:: Windows.
 
 
 .. function:: displayhook(value)
@@ -477,7 +479,7 @@ always available.
 
    Return the build time API version of Android as an integer.
 
-   Availability: Android.
+   .. availability:: Android.
 
    .. versionadded:: 3.7
 
@@ -501,7 +503,9 @@ always available.
    Return the current value of the flags that are used for
    :c:func:`dlopen` calls.  Symbolic names for the flag values can be
    found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
-   :data:`os.RTLD_LAZY`).  Availability: Unix.
+   :data:`os.RTLD_LAZY`).
+
+   .. availability:: Unix.
 
 
 .. function:: getfilesystemencoding()
@@ -669,7 +673,7 @@ always available.
    is being emulated for the process. It is intended for use in logging rather
    than for feature detection.
 
-   Availability: Windows.
+   .. availability:: Windows.
 
    .. versionchanged:: 3.2
       Changed to a named tuple and added *service_pack_minor*,
@@ -1094,7 +1098,7 @@ always available.
    can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g.
    :data:`os.RTLD_LAZY`).
 
-   Availability: Unix.
+   .. availability:: Unix.
 
 .. function:: setprofile(profilefunc)
 
@@ -1340,7 +1344,7 @@ always available.
    This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING`
    environment variable before launching Python.
 
-   Availability: Windows
+   .. availability:: Windows.
 
    .. versionadded:: 3.6
       See :pep:`529` for more details.
@@ -1486,7 +1490,9 @@ always available.
    stored as string resource 1000 in the Python DLL.  The value is normally the
    first three characters of :const:`version`.  It is provided in the :mod:`sys`
    module for informational purposes; modifying this value has no effect on the
-   registry keys used by Python. Availability: Windows.
+   registry keys used by Python.
+
+   .. availability:: Windows.
 
 
 .. data:: _xoptions

Doc/library/threading.rst

@@ -100,7 +100,8 @@ This module defines the following functions:
    memory page size - platform documentation should be referred to for more
    information (4 KiB pages are common; using multiples of 4096 for the stack size is
    the suggested approach in the absence of more specific information).
-   Availability: Windows, systems with POSIX threads.
+
+   .. availability:: Windows, systems with POSIX threads.
 
 
 This module also defines the following constant:

Doc/library/time.rst

@@ -170,8 +170,8 @@ Functions
       Passing an invalid or expired *thread_id* may result in
       undefined behavior, such as segmentation fault.
 
-   Availability: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for
-   further information)
+   .. availability:: Unix (see the man page for :manpage:`pthread_getcpuclockid(3)` for
+      further information).
 
    .. versionadded:: 3.7
 
@@ -180,7 +180,7 @@ Functions
    Return the resolution (precision) of the specified clock *clk_id*.  Refer to
    :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -190,7 +190,7 @@ Functions
    Return the time of the specified clock *clk_id*.  Refer to
    :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -199,7 +199,7 @@ Functions
 
    Similar to :func:`clock_gettime` but return time as nanoseconds.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -209,7 +209,7 @@ Functions
    Set the time of the specified clock *clk_id*.  Currently,
    :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -218,7 +218,7 @@ Functions
 
    Similar to :func:`clock_settime` but set time with nanoseconds.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.7
 
@@ -617,8 +617,8 @@ Functions
    returned value is undefined, so that only the difference between the results
    of consecutive calls in the same thread is valid.
 
-   Availability:  Windows, Linux, Unix systems supporting
-   ``CLOCK_THREAD_CPUTIME_ID``.
+   .. availability::  Windows, Linux, Unix systems supporting
+      ``CLOCK_THREAD_CPUTIME_ID``.
 
    .. versionadded:: 3.7
 
@@ -647,7 +647,7 @@ Functions
    nonzero if there is a time, past, present or future when daylight saving time
    applies).
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. note::
 
@@ -743,7 +743,7 @@ These constants are used as parameters for :func:`clock_getres` and
    have  discontinuities if the time is changed using ``settimeofday()`` or
    similar.
 
-   Availability: Linux 2.6.39 or later.
+   .. availability:: Linux 2.6.39 or later.
 
    .. versionadded:: 3.7
 
@@ -754,7 +754,7 @@ These constants are used as parameters for :func:`clock_getres` and
    hardware source, and may give close to nanosecond resolution.
    ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.
 
-   Availability: Solaris.
+   .. availability:: Solaris.
 
    .. versionadded:: 3.3
 
@@ -764,7 +764,7 @@ These constants are used as parameters for :func:`clock_getres` and
    Clock that cannot be set and represents monotonic time since some unspecified
    starting point.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -783,7 +783,7 @@ These constants are used as parameters for :func:`clock_getres` and
 
    High-resolution per-process timer from the CPU.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 
@@ -792,7 +792,7 @@ These constants are used as parameters for :func:`clock_getres` and
 
    High-resolution per-process timer from the CPU.
 
-   Availability: FreeBSD, NetBSD 7 or later, OpenBSD.
+   .. availability:: FreeBSD, NetBSD 7 or later, OpenBSD.
 
    .. versionadded:: 3.7
 
@@ -812,7 +812,7 @@ These constants are used as parameters for :func:`clock_getres` and
    suspended, providing accurate uptime measurement, both absolute and
    interval.
 
-   Availability: FreeBSD, OpenBSD 5.5 or later.
+   .. availability:: FreeBSD, OpenBSD 5.5 or later.
 
    .. versionadded:: 3.7
 
@@ -825,7 +825,7 @@ The following constant is the only parameter that can be sent to
    System-wide real-time clock.  Setting this clock requires appropriate
    privileges.
 
-   Availability: Unix.
+   .. availability:: Unix.
 
    .. versionadded:: 3.3
 

Doc/tools/extensions/pyspecific.py

@@ -131,6 +131,25 @@ class ImplementationDetail(Directive):
         return [pnode]
 
 
+# Support for documenting platform availability
+
+class Availability(Directive):
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+
+    def run(self):
+        pnode = nodes.paragraph(classes=['availability'])
+        n, m = self.state.inline_text(':ref:`Availability <availability>`: ',
+                                      self.lineno)
+        pnode.extend(n + m)
+        n, m = self.state.inline_text(self.arguments[0], self.lineno)
+        pnode.extend(n + m)
+        return [pnode]
+
+
 # Support for documenting decorators
 
 class PyDecoratorMixin(object):
@@ -401,6 +420,7 @@ def setup(app):
     app.add_role('issue', issue_role)
     app.add_role('source', source_role)
     app.add_directive('impl-detail', ImplementationDetail)
+    app.add_directive('availability', Availability)
     app.add_directive('deprecated-removed', DeprecatedRemoved)
     app.add_builder(PydocTopicsBuilder)
     app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)

Doc/tools/rstlint.py

@@ -27,17 +27,18 @@ directives = [
     'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning',
     # Sphinx and Python docs custom ones
     'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata',
-    'autoexception', 'autofunction', 'automethod', 'automodule', 'centered',
-    'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember',
-    'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar',
-    'data', 'decorator', 'decoratormethod', 'deprecated-removed',
-    'deprecated(?!-removed)', 'describe', 'directive', 'doctest', 'envvar',
-    'event', 'exception', 'function', 'glossary', 'highlight', 'highlightlang',
-    'impl-detail', 'index', 'literalinclude', 'method', 'miscnews', 'module',
-    'moduleauthor', 'opcode', 'pdbcommand', 'productionlist',
-    'program', 'role', 'sectionauthor', 'seealso', 'sourcecode', 'staticmethod',
-    'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo',
-    'todolist', 'versionadded', 'versionchanged'
+    'autoexception', 'autofunction', 'automethod', 'automodule',
+    'availability', 'centered', 'cfunction', 'class', 'classmethod', 'cmacro',
+    'cmdoption', 'cmember', 'code-block', 'confval', 'cssclass', 'ctype',
+    'currentmodule', 'cvar', 'data', 'decorator', 'decoratormethod',
+    'deprecated-removed', 'deprecated(?!-removed)', 'describe', 'directive',
+    'doctest', 'envvar', 'event', 'exception', 'function', 'glossary',
+    'highlight', 'highlightlang', 'impl-detail', 'index', 'literalinclude',
+    'method', 'miscnews', 'module', 'moduleauthor', 'opcode', 'pdbcommand',
+    'productionlist', 'program', 'role', 'sectionauthor', 'seealso',
+    'sourcecode', 'staticmethod', 'tabularcolumns', 'testcode', 'testoutput',
+    'testsetup', 'toctree', 'todo', 'todolist', 'versionadded',
+    'versionchanged'
 ]
 
 all_directives = '(' + '|'.join(directives) + ')'

Doc/using/cmdline.rst

@@ -785,7 +785,7 @@ conflict.
    This may also be enabled at runtime with
    :func:`sys._enablelegacywindowsfsencoding()`.
 
-   Availability: Windows
+   .. availability:: Windows.
 
    .. versionadded:: 3.6
       See :pep:`529` for more details.
@@ -799,7 +799,7 @@ conflict.
    This variable is ignored if the standard streams are redirected (to files
    or pipes) rather than referring to console buffers.
 
-   Availability: Windows
+   .. availability:: Windows.
 
    .. versionadded:: 3.6
 
@@ -850,7 +850,7 @@ conflict.
    order to force the interpreter to use ``ASCII`` instead of ``UTF-8`` for
    system interfaces.
 
-   Availability: \*nix
+   .. availability:: \*nix.
 
    .. versionadded:: 3.7
       See :pep:`538` for more details.
@@ -911,7 +911,7 @@ conflict.
 
    Also available as the :option:`-X` ``utf8`` option.
 
-   Availability: \*nix
+   .. availability:: \*nix.
 
    .. versionadded:: 3.7
       See :pep:`540` for more details.

Misc/NEWS.d/next/Documentation/2018-10-03-20-39-25.bpo-11233.BX6Gen.rst

+Create availability directive for documentation.  Original patch by Georg
+Brandl.