Philip Durbin 🚀 (Sep 26 2025 at 15:57): Philip Durbin 🚀 (Sep 26 2025 at 15:57):In the meeting today we went over how to add a ref manually. I mentioned that there's an extension to automate it: https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
Technically, the thing you link to is called a label. We add them above a header like this:
.. _account-log-in-options:
Account Log In Options
~~~~~~~~~~~~~~~~~~~~~~
I had a quick play with sphinx.ext.autosectionlabel but there's a downside. We won't be able to use the same heading twice on the same page. For example, at https://guides.dataverse.org/en/6.8/admin/integrations.html we have Open OnDemand under both "getting data in" and "analysis and computation".
https://docs.openedx.org/en/open-release-palm.master/documentors/decisions/0004-no-auto-section-label.html mentions the problem above and says it's hard to debug.
I dunno, maybe we could try sphinx.ext.autosectionlabel on a smaller Sphinx site like the one at https://github.com/IQSS/dataverse-hub first to see if we even like it. 
Philip Durbin 🚀 (Sep 26 2025 at 18:02):This is the change I made locally to test the extension:
diff --git a/doc/sphinx-guides/source/conf.py b/doc/sphinx-guides/source/conf.py
index abf6ba7379..af64cd5ecb 100755
--- a/doc/sphinx-guides/source/conf.py
+++ b/doc/sphinx-guides/source/conf.py
@@ -47,6 +47,7 @@ extensions = [
'myst_parser',
'sphinx_tabs.tabs',
'sphinx_substitution_extensions',
+ 'sphinx.ext.autosectionlabel',
]
# Add any paths that contain templates here, relative to this directory.
@@ -442,3 +443,5 @@ rst_prolog = """
.. |version| replace:: %s
.. |nextVersion| replace:: %s
""" % (version, "%s.%s" % semver.Version.parse(version, optional_minor_and_patch=True).bump_minor().to_tuple()[0:2] )
+
+autosectionlabel_prefix_document = True
\ No newline at end of file
This is what the "two headings on the same page" error looks like:
/Users/pdurbin/github/iqss/guides.dataverse.org/doc/sphinx-guides/source/admin/integrations.rst:232:duplicate label admin/integrations:open ondemand, other instance in /Users/pdurbin/github/iqss/guides.dataverse.org/doc/sphinx-guides/source/admin/integrations.rst
Last updated: Nov 01 2025 at 14:11 UTC