Discourage references in section headings.

QuLogic · QuLogic · commit 177d0555da40 · 2020-07-24T00:25:46.000-04:00
This mostly affects what's new/API changes, so put the suggestion there.
diff --git a/doc/api/next_api_changes/README.rst b/doc/api/next_api_changes/README.rst
@@ -22,7 +22,9 @@ author's initials. Typically, each change will get its own file, but you may
 also amend existing files when suitable. The overall goal is a comprehensible
 documentation of the changes.
 
-A typical entry could look like this::
+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. A typical entry could look like this::
 
    Locators
    ~~~~~~~~
diff --git a/doc/users/next_whats_new/README.rst b/doc/users/next_whats_new/README.rst
@@ -9,7 +9,11 @@ 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
 something like :file:`cool_new_feature.rst` if you have added a brand new
 feature or something like :file:`updated_feature.rst` for extensions of
-existing features.  Include contents of the form: ::
+existing features.
+
+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.  Include contents of the form: ::
 
     Section Title for Feature
     -------------------------
