Use the sphinx-better-subsection extension to use explicit targets for section permalinks

CHANGES.rst

@@ -2,6 +2,19 @@
 Changelog
 =========
 
+Unreleased
+==========
+
+The ``sphinx-better-subsection`` extension is installed and automatically set
+up to prefer explicit targets for a section heading over auto-generated targets
+(e.g. from the title) when producing HTML permalinks.  This change is backwards
+compatible as both targets still work in both rST and HTML pages.  An example
+can be seen below for the `previous release heading <v2023.1_>`__.
+(`#38 <https://github.com/nextstrain/sphinx-theme/pull/38>`_)
+
+
+.. _v2023.1:
+
 2023.1 (16 February 2023)
 =========================
 

doc/demo/demo.rst

@@ -308,6 +308,9 @@ This is a glossary with definition terms for thing like :term:`Writing`:
   Writing
      The process of putting thoughts into a medium for other people to :term:`read <Reading>`.
 
+
+.. _preferred:
+
 Targets
 -------
 
@@ -318,7 +321,8 @@ A reference can be found under `Inline Markup`_, above. `Inline
 hyperlink targets`_ are also possible.
 
 Section headers are implicit targets, referred to by name. See
-Targets_, which is a subsection of `Paragraph Level Markup`_.
+Targets_, which is a subsection of `Paragraph Level Markup`_. Explicit targets
+before a section heading are preferred_ when generating HTML permalinks.
 
 Explicit external targets are interpolated into references such as "Python_".
 

lib/nextstrain/sphinx/theme/__init__.py

@@ -15,6 +15,7 @@
 
 def setup(app):
     app.add_html_theme('nextstrain-sphinx-theme', str(package_dir))
+    app.setup_extension('sphinx_better_subsection')
     app.setup_extension('sphinx_copybutton')
     # customize sphinx_copybutton https://sphinx-copybutton.readthedocs.io/en/latest/use.html
     app.config['copybutton_prompt_text'] = '$ '

setup.py

@@ -34,7 +34,8 @@
     },
     install_requires = [
         'sphinx_rtd_theme >=1.0.0',
-        'sphinx-copybutton'
+        'sphinx-better-subsection',
+        'sphinx-copybutton',
     ],
     classifiers = [
         'Framework :: Sphinx',