Remove :platform: doc, add .. availability:: (GH-1744)

StanFromIreland · web-flow · commit cf022dfcc895 · 2026-03-06T21:27:22.000+01:00
diff --git a/documentation/markup.rst b/documentation/markup.rst
@@ -357,11 +357,10 @@ module being documented.  Each module should be documented in its own file.
 Normally this markup appears after the title heading of that file; a typical
 file might start like this::
 
-   :mod:`parrot` -- Dead parrot access
-   ===================================
+   :mod:`!parrot` -- Dead parrot access
+   ====================================
 
    .. module:: parrot
-      :platform: Unix, Windows
       :synopsis: Analyze and reanimate dead parrots.
 
 .. describe:: module
@@ -370,12 +369,6 @@ file might start like this::
    or submodule. The name should be fully qualified (that is, including the
    package name for submodules).
 
-   The ``platform`` option, if present, is a comma-separated list of the
-   platforms on which the module is available (if it is available on all
-   platforms, the option should be omitted).  The keys are short identifiers;
-   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
-   important to use a key which has already been used when applicable.
-
    The ``synopsis`` option should consist of one sentence describing the
    module's purpose -- it is currently only used in the Global Module Index.
 
@@ -1030,6 +1023,17 @@ Paragraph-level markup
 These directives create short paragraphs and can be used inside information
 units as well as normal text:
 
+.. describe:: availability
+
+   This directive documents the platforms on which a module or feature
+   is available. For example::
+
+      .. availability:: Unix, not WASI, not Android.
+
+   ::
+
+      .. availability:: Linux >= 3.0 with glibc >= 2.14.
+
 .. describe:: note
 
    An especially important bit of information about an API that a user should be
