DOC: Fix inclusion of next API/what's new instructions

QuLogic · QuLogic · commit 42bfa268429e · 2024-07-30T22:30:56.000-04:00
diff --git a/doc/api/next_api_changes/README.rst b/doc/api/next_api_changes/README.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
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -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
diff --git a/doc/users/next_whats_new/README.rst b/doc/users/next_whats_new/README.rst
@@ -1,10 +1,19 @@
 :orphan:
 
+.. NOTE TO EDITORS OF THIS FILE
+   This file serves as the README directly available in the file system next to the
+   next_whats_new entries. The content between the ``whats-new-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.
+
+
 Instructions for writing "What's new" entries
 =============================================
 
-Please place new portions of :file:`whats_new.rst` in the :file:`next_whats_new`
-directory.
+.. whats-new-guide-start
+
+Please place new portions of :file:`whats_new.rst` in the
+:file:`doc/users/next_whats_new/` directory.
 
 When adding an entry please look at the currently existing files to
 see if you can extend any of them.  If you create a file, name it
@@ -27,6 +36,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-24 of this file are include in :ref:`api_whats_new`;
-   therefore, please check the doc build after changing this file.
+.. whats-new-guide-end
