doc: fix version number; add sphinx-hoverxref

.readthedocs.yaml

@@ -13,3 +13,7 @@ build:
   os: "ubuntu-22.04"
   tools:
     python: "3.12"
+
+python:
+  install:
+    - requirements: doc/requirements.txt

doc/conf.py

@@ -3,22 +3,40 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import warnings
+
+import setuptools_scm
+
+# for hoverxref<=1.5.0
+warnings.filterwarnings(
+    "ignore",
+    category=DeprecationWarning,
+    message="The '_Opt' object tuple interface is deprecated, use attribute access instead for 'default', 'rebuild', and 'valid_types'",
+)
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "C-COMPASS"
 copyright = "2024, Daniel Haas"
 author = "Daniel Haas"
-release = "1.0.0"
+version = release = setuptools_scm.get_version(root="..", relative_to=__file__)
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = ["hoverxref.extension"]
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+# hoverxref configuration
+hoverxref_auto_ref = True
+hoverxref_roles = [
+    "numref",
+    "confval",
+    "setting",
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

doc/requirements.txt

@@ -0,0 +1,2 @@
+setuptools-scm
+sphinx-hoverxref

pyproject.toml

@@ -46,7 +46,7 @@ ccompass = "ccompass.__main__:main"
 
 [project.optional-dependencies]
 dev = ["pre-commit>=3", "pytest", "tox"]
-doc = ["sphinx", "sphinx-rtd-theme"]
+doc = ["sphinx", "sphinx-rtd-theme", "sphinx-hoverxref", "setuptools-scm"]
 test = ["pytest"]
 
 [project.urls]