Merge branch 'main' into axesbase_twinx_type_hint

Author: randolf-scholz

doc/_templates/autofunctions.rst

@@ -5,11 +5,40 @@ Next API changes
 
 .. ifconfig:: releaselevel == 'dev'
 
+   This page lists API changes for the next release.
+
+   Behavior changes
+   ----------------
+
    .. toctree::
       :glob:
       :maxdepth: 1
 
       next_api_changes/behavior/*
+
+   Deprecations
+   ------------
+
+   .. toctree::
+      :glob:
+      :maxdepth: 1
+
       next_api_changes/deprecations/*
-      next_api_changes/development/*
+
+   Removals
+   --------
+
+   .. toctree::
+      :glob:
+      :maxdepth: 1
+
       next_api_changes/removals/*
+
+   Development changes
+   -------------------
+
+   .. toctree::
+      :glob:
+      :maxdepth: 1
+
+      next_api_changes/development/*

doc/api/next_api_changes.rst

@@ -1,10 +1,18 @@
 :orphan:
 
+.. NOTE TO EDITORS OF THIS FILE
+   This file serves as the README directly available in the file system next to the
+   next_api_changes entries. The content between the ``api-change-guide-*`` markers is
+   additionally included in the documentation page ``doc/devel/api_changes.rst``. Please
+   check that the page builds correctly after changing this file.
+
 Adding API change notes
 =======================
 
-API change notes for future releases are collected in
-:file:`next_api_changes`. They are divided into four subdirectories:
+.. api-change-guide-start
+
+API change notes for future releases are collected in :file:`doc/api/next_api_changes/`.
+They are divided into four subdirectories:
 
 - **Deprecations**: Announcements of future changes. Typically, these will
   raise a deprecation warning and users of this API should change their code
@@ -33,6 +41,4 @@ 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.
 
-.. NOTE
-   Lines 5-30 of this file are include in :ref:`api_whats_new`;
-   therefore, please check the doc build after changing this file.
+.. api-change-guide-end

doc/api/next_api_changes/README.rst

@@ -360,8 +360,8 @@ def gallery_image_warning_filter(record):
 # This is the default encoding, but it doesn't hurt to be explicit
 source_encoding = "utf-8"
 
-# The toplevel toctree document (renamed to root_doc in Sphinx 4.0)
-root_doc = master_doc = 'index'
+# The toplevel toctree document.
+root_doc = 'index'
 
 # General substitutions.
 try:

doc/conf.py

@@ -216,14 +216,14 @@ API change notes
 """"""""""""""""
 
 .. include:: ../api/next_api_changes/README.rst
-   :start-line: 5
-   :end-line: 31
+   :start-after: api-change-guide-start
+   :end-before: api-change-guide-end
 
 .. _whats-new-notes:
 
 What's new notes
 """"""""""""""""
 
 .. include:: ../users/next_whats_new/README.rst
-   :start-line: 5
-   :end-line: 24
+   :start-after: whats-new-guide-start
+   :end-before: whats-new-guide-end