Add config to fix or silence most autodoc broken reference warnings

Author: CAM-Gerlach

docs/conf.py

@@ -37,7 +37,7 @@
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = "5"
+needs_sphinx = "6.2"
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named "sphinx.ext.*") or your custom ones.
@@ -103,9 +103,37 @@
 # pylint: disable-next = consider-using-namedtuple-or-dataclass
 intersphinx_mapping = {
     "python": ("https://docs.python.org/", None),
+    "PyQt5": ("https://www.riverbankcomputing.com/static/Docs/PyQt5/", None),
     "spyder": ("https://docs.spyder-ide.org/current/", None),
 }
 
+# Warning suppression
+suppress_warnings = []
+
+# Nitpick warning ignore list
+nitpick_ignore_regex = {
+    # Spyder modules currently not included in the build
+    (
+        "py:.+",
+        # pylint: disable-next = line-too-long
+        "spyder.(app|config|fonts|images|locale|plugins|tests|utils|widgets|windows).*",  # noqa: E501
+    ),
+    # Numpydoc optional
+    ("py:class", "optional"),
+    # Typing params
+    ("py:.+", ".*_P"),
+    ("py:.+", ".*_RT"),
+    ("py:.+", ".*_T"),
+    # Cannot use type aliases to fix refs inside type aliases or class bases
+    ("py:class", "asyncio.events.AbstractEventLoop"),
+    ("py:class", "concurrent.futures._base.Future"),
+    # Type aliases don't work properly in Sphinx <9
+    ("py:class", "LoopID"),
+    ("py:class", "OptionSet"),
+    ("py:class", "spyder.api.preferences.OptionSet"),
+}
+
+
 # -- Options for HTML output -------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -135,9 +163,6 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# Warning suppression
-suppress_warnings = []
-
 
 # -- Options for HTMLHelp output ---------------------------------------
 
@@ -260,6 +285,28 @@
     # "qstylizer",
 ]
 
+# Configure type aliases for signatures
+autodoc_type_aliases = {
+    # Actual type aliases
+    "LoopID": "spyder.api.asyncdispatcher.LoopID",
+    "OptionSet": "spyder.api.preferences.OptionSet",
+    # Ref name aliases
+    "AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "asyncio.AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "asyncio.events.AbstractEventLoop": "asyncio.AbstractEventLoop",
+    "Future": "concurrent.futures.Future",
+    "concurrent.futures.Future": "concurrent.futures.Future",
+    "concurrent.futures._base.Future": "concurrent.futures.Future",
+}
+
+# Monkeypatch to fix type aliases not working in classmethods with Sphinx
+# See sphinx-doc/sphinx#10333
+# pylint: disable-next = wrong-import-position
+from sphinx.util import inspect  # noqa: E402
+
+inspect.TypeAliasForwardRef.__repr__ = lambda self: self.name
+inspect.TypeAliasForwardRef.__hash__ = lambda self: hash(self.name)
+
 # Set list of modules and patterns to ignore in the autosummary template
 autosummary_context = {
     "ignore_module_pattern": "tests",
@@ -276,10 +323,11 @@
 if "autodoc" in tags:  # noqa: F821
     autosummary_generate = True
     os.environ["SPHINX_AUTODOC"] = "1"
+    extensions.append("sphinx_qt_documentation")  # Errors out w/o Qt installed
 else:
     autosummary_generate = False
-    suppress_warnings += ["autodoc", "autosummary", "toc.excluded"]
     exclude_patterns += ["reference.rst"]
+    suppress_warnings += ["autodoc", "autosummary", "toc.excluded"]
 
 
 # -- Additional Directives ---------------------------------------------------

requirements.txt

@@ -1,3 +1,4 @@
 myst-parser>=1,<5  # Docs markup; cap to support wide range of py versions
-sphinx>=5,<9  # Docs generator; cap to range confirmed supported by deps
+sphinx>=6.2,<9  # Docs generator; cap to range confirmed supported by deps
 sphinx-book-theme>=1,<2  # Docs theme; cap to support wide range of py versions
+sphinx-qt-documentation>=0.4.1,<1  # Crossrefs to Qt documentation