Remove dependency on sphinx-autodoc-typehints (#9705)

* Remove dependency on sphinx-autodoc-typehints

This replaces the whole usage of the separate package
`sphinx-autodoc-typehints` with the built-in support from `autodoc`,
available (with this combination of options) since Sphinx 5.0.  This
removes a docs dependency that has caused us significant problems before
due to its instability, and the built-in handling in `autodoc` is much
cleaner as well; rather than trying to textually modify the docstring,
this version (correctly) mutates the parsed rST structure, which also
naturally it 100% compatible with the Napoleon processing.

* Maintain previous type-hint behaviour

docs/conf.py

@@ -34,7 +34,6 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
-    "sphinx_autodoc_typehints",
     "reno.sphinxext",
     "sphinx_design",
     "matplotlib.sphinxext.plot_directive",
@@ -83,6 +82,13 @@
 # documentation created by autosummary uses a template file (in autosummary in the templates path),
 # which likely overrides the autodoc defaults.
 
+# Move type hints from signatures to the parameter descriptions (except in overload cases, where
+# that's not possible).
+autodoc_typehints = "description"
+# Only add type hints from signature to description body if the parameter has documentation.  The
+# return type is always added to the description (if in the signature).
+autodoc_typehints_description_target = "documented_params"
+
 autosummary_generate = True
 autosummary_generate_overwrite = False
 

requirements-dev.txt

@@ -16,9 +16,8 @@ pylatexenc>=1.4
 ddt>=1.2.0,!=1.4.0,!=1.4.3
 seaborn>=0.9.0
 reno>=3.4.0
-Sphinx>=3.0.0
+Sphinx>=5.0
 qiskit-sphinx-theme>=1.6
-sphinx-autodoc-typehints==1.21.1  # revert to >=1.18 once the incompatibilities are fixed
 sphinx-design>=0.2.0
 pygments>=2.4
 scikit-learn>=0.20.0