From 177d0555da4028b0ecb2f849b6716ef4ea7a7a82 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Fri, 24 Jul 2020 00:25:46 -0400 Subject: [PATCH] Discourage references in section headings. This mostly affects what's new/API changes, so put the suggestion there. --- doc/api/next_api_changes/README.rst | 4 +++- doc/users/next_whats_new/README.rst | 6 +++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/api/next_api_changes/README.rst b/doc/api/next_api_changes/README.rst index 457a9d370923..de494911e6b2 100644 --- 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 index 8786be822018..6555d229a1b5 100644 --- 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 -------------------------