doc: api: Clean up and reorganize a bit

Move the section describing the requirements for a new API out of the
peripheral API header, clarify the requirements for upgrading an API to
experimental and unstable clearly in the corresponding sections. Add a
link to the API stability page.

Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>

doc/development_process/api_lifecycle.rst

@@ -17,6 +17,8 @@ no longer optimal or supported by the underlying platforms.
 
     API Life Cycle
 
+An up-to-date table of all APIs and their maturity level can be found in the
+:ref:`api_stability` page.
 
 Experimental
 *************
@@ -25,6 +27,15 @@ Experimental APIs denote that a feature was introduced recently, and may change
 or be removed in future versions. Try it out and provide feedback
 to the community via the `Developer mailing list <https://lists.zephyrproject.org/g/devel>`_.
 
+The following requirements apply to all new APIs:
+
+- Documentation of the API (usage)
+  explaining its design and assumptions, how it is to be used, current
+  implementation limitations, and future potential, if appropriate.
+- The API introduction should be accompanied by at least one implementation
+  of said API (in the case of peripheral APIs, this corresponds to one driver)
+- At least one sample using the new API (may only build on one single board)
+
 Peripheral APIs (Hardware Related)
 ==================================
 
@@ -32,25 +43,9 @@ When introducing an API (public header file with documentation) for a new
 peripheral or driver subsystem, review of the API is enforced and is driven by
 the API working group consisting of representatives from different vendors.
 
-The following requirements apply to new APIs:
-
-- Documentation of the API (usage)
-  explaining its design and assumptions, how it is to be used, current
-  implementation limitations, and future potential, if appropriate.
-- The API introduction should be accompanied by at least one driver
-  implementing this API
-- At least one sample using the new API
-
 The API shall be promoted to ``unstable`` when it has at least two
 implementations on different hardware platforms.
 
-Hardware Agnostic APIs
-=======================
-
-For hardware agnostic APIs, multiple applications are required to promote an
-API from ``experimental`` to ``unstable``.
-
-
 Unstable
 ********
 
@@ -62,6 +57,18 @@ be used on different hardware platforms.
 
    Changes will not be announced.
 
+Peripheral APIs (Hardware Related)
+==================================
+
+The API shall be promoted from ``experimental`` to ``unstable`` when it has at
+least two implementations on different hardware platforms.
+
+Hardware Agnostic APIs
+=======================
+
+For hardware agnostic APIs, multiple applications using it are required to
+promote an API from ``experimental`` to ``unstable``.
+
 Stable
 *******