Fixups for recent changes in sphinx dependencies (#954)

# Pull Request

## Title

Fixups for recent changes in sphinx dependencies

______________________________________________________________________

## Description

- Changes the type resolution for a few type aliases from `data` to
`type`
- Excludes flaml's `Domain` type from resolution.
- Excludes `Future` from resolution nitpick (similar error to
`Ellipsis`)
- Documents the new versions that caused these.

______________________________________________________________________

## Type of Change

- 🛠️ Bug fix
- 📝 Documentation update

______________________________________________________________________

Author: bpkroth

doc/requirements.txt

@@ -1,6 +1,6 @@
 setuptools-scm>=8.1.0
-sphinx
-sphinx-autoapi
+sphinx>=8.2.0
+sphinx-autoapi>=3.6.0
 intersphinx_registry>=0.2501.23 # https://github.com/Quansight-Labs/intersphinx_registry/pull/58
 nbsphinx
 jupyter_core>=4.11.2    # nbsphix dependency - addresses CVE-2022-39286

doc/source/conf.py

@@ -167,17 +167,17 @@ def is_on_github_actions():
     ("ConcreteSpaceAdapter", "class"): "data",
     ("DistributionName", "class"): "data",
     ("mlos_bench.tunables.tunable_types.DistributionName", "class"): "data",
-    ("FlamlDomain", "class"): "data",
-    ("mlos_core.spaces.converters.flaml.FlamlDomain", "class"): "data",
-    ("TunableValue", "class"): "data",
-    ("mlos_bench.tunables.tunable_types.TunableValue", "class"): "data",
-    ("TunableValueType", "class"): "data",
-    ("mlos_bench.tunables.tunable_types.TunableValueType", "class"): "data",
+    ("FlamlDomain", "class"): "type",
+    ("mlos_core.spaces.converters.flaml.FlamlDomain", "class"): "type",
+    ("TunableValue", "class"): "type",
+    ("mlos_bench.tunables.tunable_types.TunableValue", "class"): "type",
+    ("TunableValueType", "class"): "type",
+    ("mlos_bench.tunables.tunable_types.TunableValueType", "class"): "type",
     ("TunableValueTypeName", "class"): "data",
     ("mlos_bench.tunables.tunable_types.TunableValueTypeName", "class"): "data",
     ("T_co", "class"): "data",
     ("CoroReturnType", "class"): "data",
-    ("FutureReturnType", "class"): "data",
+    ("FutureReturnType", "class"): "type",
     ("NullableT", "class"): "data",
 }
 
@@ -192,10 +192,11 @@ def resolve_type_aliases(
     if node["refdomain"] != "py":
         return None
     (orig_type, reftarget) = (node["reftype"], node["reftarget"])
+    # warning(f"Resolving {orig_type} {reftarget}...")
     new_type = CUSTOM_REF_TYPE_MAP.get((reftarget, orig_type))
     if new_type:
         # warning(f"Resolved {orig_type} {reftarget} to {new_type}")
-        return app.env.get_domain("py").resolve_xref(
+        resolved = app.env.get_domain("py").resolve_xref(
             env,
             node["refdoc"],
             app.builder,
@@ -204,6 +205,8 @@ def resolve_type_aliases(
             node,
             contnode,
         )
+        # warning(f"Resolved {orig_type} {reftarget} to xref {resolved}")
+        return resolved
     return None
 
 
@@ -216,6 +219,7 @@ def setup(app: SphinxApp) -> None:
 # sphinx has a hard time finding typealiases and typevars instead of classes.
 # See Also: https://github.com/sphinx-doc/sphinx/issues/10974
 nitpick_ignore = [
+    ("py:class", "Future"),
     ("py:class", "Ellipsis"),
     # Internal typevars and aliases:
     ("py:class", "EnvironType"),
@@ -229,6 +233,7 @@ def setup(app: SphinxApp) -> None:
     ("py:class", "sqlalchemy.MetaData"),
     ("py:exc", "jsonschema.exceptions.SchemaError"),
     ("py:exc", "jsonschema.exceptions.ValidationError"),
+    ("py:class", "Domain"),  # flaml
 ]
 nitpick_ignore_regex = [
     # Ignore some external references that don't use sphinx for their docs.

mlos_bench/mlos_bench/tunables/tunable_types.py

@@ -42,7 +42,7 @@
 
 Notes
 -----
-For checking whether a param is a :py:data:`.TunableValue` with
+For checking whether a param is a :py:type:`.TunableValue` with
 :py:func:`isinstance`.
 """