update api_changes and coding guide to make api more prominant and attempt redirect

story645 · story645 · commit 9b8c6605460a · 2024-01-14T19:01:28.000-05:00
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -1,7 +1,7 @@
 .. _api_changes:
 
-API changes
-===========
+API guidelines
+==============
 
 API consistency and stability are of great value; Therefore, API changes
 (e.g. signature changes, behavior changes, removals) will only be conducted
@@ -17,10 +17,12 @@ are backwards-incompatible API changes.
 
    color_changes.rst
 
+.. redirect-from:: /devel/coding_guide#new-features-and-api-changes
+
 .. _api_whats_new:
 
-Announce changes, deprecations, and new features
-------------------------------------------------
+Announce new features, API changes, and deprecations
+----------------------------------------------------
 
 When adding or changing the API in a backward in-compatible way, please add the
 appropriate :ref:`versioning directive <versioning-directives>` and document it
@@ -34,10 +36,9 @@ for the release notes and add the entry to the appropriate folder:
 | API change        | ``.. versionchanged:: 3.N`` | :file:`doc/api/next_api_changes/[kind]`      |
 +-------------------+-----------------------------+----------------------------------------------+
 
-API deprecations are first introduced and then expired. During the introduction
-period, users are warned that the API *will* change in the future.
-During the expiration period, code is changed as described in the notice posted
-during the introductory period.
+API deprecations are first introduced and then expired. During the introduction period,
+users are warned that the API *will* change in the future. During the expiration period,
+code *is* changed as described in the notice posted during the introductory period.
 
 +-----------+--------------------------------------------------+----------------------------------------------+
 |   stage   |                 required changes                 |             announcement folder              |
@@ -47,27 +48,95 @@ during the introductory period.
 | expire    | :ref:`expire deprecation <expire-deprecation>`   | :file:`doc/api/next_api_changes/[kind]`      |
 +-----------+--------------------------------------------------+----------------------------------------------+
 
-For both change notes and what's new, please avoid using references in section
-titles, as it causes links to be confusing in the table of contents. Instead,
-ensure that a reference is included in the descriptive text.
+.. _versioning-directives:
+
+Versioning directives
+^^^^^^^^^^^^^^^^^^^^^
+
+When making a backward incompatible change, please add a versioning directive in
+the docstring. The directives should be placed at the end of a description block.
+For example::
+
+  class Foo:
+      """
+      This is the summary.
+
+      Followed by a longer description block.
+
+      Consisting of multiple lines and paragraphs.
+
+      .. versionadded:: 3.5
+
+      Parameters
+      ----------
+      a : int
+          The first parameter.
+      b: bool, default: False
+          This was added later.
+
+          .. versionadded:: 3.6
+      """
+
+      def set_b(b):
+          """
+          Set b.
+
+          .. versionadded:: 3.6
+
+          Parameters
+          ----------
+          b: bool
+
+For classes and functions, the directive should be placed before the
+*Parameters* section. For parameters, the directive should be placed at the
+end of the parameter description. The patch release version is omitted and
+the directive should not be added to entire modules.
+
+Release notes
+^^^^^^^^^^^^^
 
-API Change Notes
-^^^^^^^^^^^^^^^^
+For both change notes and what's new, please avoid using references in section titles,
+as it causes links to be confusing in the table of contents. Instead, ensure that a
+reference is included in the descriptive text.
+
+API change notes
+""""""""""""""""
 
 .. include:: ../api/next_api_changes/README.rst
    :start-line: 5
    :end-line: 31
 
-What's new
-^^^^^^^^^^
+What's new notes
+""""""""""""""""
 
 .. include:: ../users/next_whats_new/README.rst
    :start-line: 5
    :end-line: 24
 
 
-Deprecation
------------
+Add new API and features
+------------------------
+
+Every new function, parameter and attribute that is not explicitly marked as
+private (i.e., starts with an underscore) becomes part of Matplotlib's public
+API. As discussed above, changing the existing API is cumbersome. Therefore,
+take particular care when adding new API:
+
+- Mark helper functions and internal attributes as private by prefixing them
+  with an underscore.
+- Carefully think about good names for your functions and variables.
+- Try to adopt patterns and naming conventions from existing parts of the
+  Matplotlib API.
+- Consider making as many arguments keyword-only as possible. See also
+  `API Evolution the Right Way -- Add Parameters Compatibly`__.
+
+  __ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters
+
+
+.. _deprecation-guidelines:
+
+Deprecate API
+-------------
 
 API changes in Matplotlib have to be performed following the deprecation process
 below, except in very rare circumstances as deemed necessary by the development
@@ -146,66 +215,3 @@ Expire deprecation
      items were never type hinted in the first place and were added to this file
      instead. For removed items that were not in the stub file, only deleting from the
      allowlist is required.
-
-Adding new API and features
----------------------------
-
-Every new function, parameter and attribute that is not explicitly marked as
-private (i.e., starts with an underscore) becomes part of Matplotlib's public
-API. As discussed above, changing the existing API is cumbersome. Therefore,
-take particular care when adding new API:
-
-- Mark helper functions and internal attributes as private by prefixing them
-  with an underscore.
-- Carefully think about good names for your functions and variables.
-- Try to adopt patterns and naming conventions from existing parts of the
-  Matplotlib API.
-- Consider making as many arguments keyword-only as possible. See also
-  `API Evolution the Right Way -- Add Parameters Compatibly`__.
-
-  __ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters
-
-
-.. _versioning-directives:
-
-Versioning directives
----------------------
-
-When making a backward incompatible change, please add a versioning directive in
-the docstring. The directives should be placed at the end of a description block.
-For example::
-
-  class Foo:
-      """
-      This is the summary.
-
-      Followed by a longer description block.
-
-      Consisting of multiple lines and paragraphs.
-
-      .. versionadded:: 3.5
-
-      Parameters
-      ----------
-      a : int
-          The first parameter.
-      b: bool, default: False
-          This was added later.
-
-          .. versionadded:: 3.6
-      """
-
-      def set_b(b):
-          """
-          Set b.
-
-          .. versionadded:: 3.6
-
-          Parameters
-          ----------
-          b: bool
-
-For classes and functions, the directive should be placed before the
-*Parameters* section. For parameters, the directive should be placed at the
-end of the parameter description. The patch release version is omitted and
-the directive should not be added to entire modules.
diff --git a/doc/devel/coding_guide.rst b/doc/devel/coding_guide.rst
@@ -4,15 +4,15 @@
 Coding guidelines
 *****************
 
+.. admonition:: API guidelines
+    :class: seealso, sidebar
+
+    If adding new features or otherwise changing API, see :ref:`api_changes`
+
+
 We appreciate these guidelines being followed because it improves the readability,
 consistency, and maintainability of the code base.
 
-API changes
-===========
-
-If you are adding new features, changing behavior or function signatures, or
-removing classes, functions, methods, or properties, please see the :ref:`api_changes`
-guide.
 
 PEP8, as enforced by flake8
 ===========================
