Fix type hints in docs for PUBs and improve Sphinx config (#2052)

Closes #1877. We now use `EstimatorPubLike` and `SamplerPubLike` for the type hints, rather than Sphinx fully expanding the types into extremely long values shown in #1877. To fix the type hints, we have to stop using `sphinx-autodoc-typehints` and instead use autodoc's builtin support for type hints. I didn't realize we were still using `sphinx-autodoc-typehints` - the other Qiskit projects migrated off a while ago. This PR also makes some other improvements to align with changes we made in Qiskit Addons & qiskit-ibm-transpiler: * always show inheritance in class pages for the base class * index page should show the PyPI package name in code syntax * don't show signatures in `autosummary` tables, since they're noisy * show type hints for parameters that don't have docstring ## Introduces a regression: type hints for properties Unfortunately, switching off of `sphinx-autodoc-typehints` results in Qiskit/documentation#2346. This is a quirk of autosummary that we cannot easily fix. We have a plan to fix it, although realistically won't get to it until Q1 and possibly Q2. In the meantime, consider repeating some of the type information in the docstring. For example, in ``` <Attribute id="qiskit_ibm_runtime.EstimatorV2.mode"> Return the execution mode used by this primitive. ``` You could rewrite to say ``` <Attribute id="qiskit_ibm_runtime.EstimatorV2.mode"> Return the execution mode used by this primitive, either :class:~`.Session` or ~:class:~`.Batch`. ```
Qiskit · Nov 25, 2024 · 7c5e87c · 7c5e87c
1 parent af083a4
commit 7c5e87c
Show file tree

Hide file tree

Showing 14 changed files with 33 additions and 26 deletions.
diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -1,23 +1,24 @@
-{% if referencefile %}
-.. include:: {{ referencefile }}
-{% endif %}
+{#
+   We show all the class's methods and attributes on the same page. By default, we document
+   all methods, including those defined by parent classes.
+-#}
 
-{{ objname }}
-{{ underline }}
+{{ objname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
    :no-members:
    :no-inherited-members:
    :no-special-members:
+   :show-inheritance:
 
 {% block attributes_summary %}
    {% if attributes %}
    .. rubric:: Attributes
       {% for item in all_attributes %}
          {%- if not item.startswith('_') %}
-   .. autoattribute:: {{ name }}.{{ item }}
+   .. autoattribute:: {{ item }}
          {%- endif -%}
       {%- endfor %}
    {% endif %}
@@ -28,7 +29,7 @@
    .. rubric:: Methods
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-   .. automethod:: {{ name }}.{{ item }}
+   .. automethod:: {{ item }}
       {%- endif -%}
    {%- endfor %}
 

diff --git a/docs/apidocs/index.rst b/docs/apidocs/index.rst
@@ -1,8 +1,8 @@
 .. vale off
 
-********************************
-qiskit-ibm-runtime API reference
-********************************
+************************************
+``qiskit-ibm-runtime`` API reference
+************************************
 
 .. toctree::
    :maxdepth: 1

diff --git a/docs/conf.py b/docs/conf.py
@@ -39,7 +39,6 @@
     # This is used by qiskit/documentation to generate links to github.com.
     "sphinx.ext.linkcode",
     'jupyter_sphinx',
-    'sphinx_autodoc_typehints',
     'nbsphinx',
     'sphinxcontrib.katex',
     'matplotlib.sphinxext.plot_directive',
@@ -83,10 +82,19 @@
 # -----------------------------------------------------------------------------
 
 autosummary_generate = True
-
+autosummary_generate_overwrite = False
+autoclass_content = "both"
+autodoc_typehints = "description"
 autodoc_default_options = {
-    'inherited-members': None,
+    "inherited-members": None,
+    "show-inheritance": True,
+}
+autodoc_type_aliases = {
+    "EstimatorPubLike": "EstimatorPubLike",
+    "SamplerPubLike": "SamplerPubLike",
 }
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
 
 
 # If true, figures, tables and code-blocks are automatically numbered if they
@@ -130,7 +138,6 @@
 
 html_last_updated_fmt = '%Y/%m/%d'
 html_sourcelink_suffix = ''
-autoclass_content = 'both'
 
 
 # ----------------------------------------------------------------------------------

diff --git a/qiskit_ibm_runtime/__init__.py b/qiskit_ibm_runtime/__init__.py
@@ -183,6 +183,7 @@
 =======
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    QiskitRuntimeService
    Estimator

diff --git a/qiskit_ibm_runtime/debug_tools/__init__.py b/qiskit_ibm_runtime/debug_tools/__init__.py
@@ -24,6 +24,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    Neat
    NeatResult

diff --git a/qiskit_ibm_runtime/execution_span/__init__.py b/qiskit_ibm_runtime/execution_span/__init__.py
@@ -29,6 +29,7 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :nosignatures:
 
     DoubleSliceSpan
     ExecutionSpan

diff --git a/qiskit_ibm_runtime/fake_provider/__init__.py b/qiskit_ibm_runtime/fake_provider/__init__.py
@@ -91,6 +91,7 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :nosignatures:
 
     FakeProviderForBackendV2
 
@@ -106,6 +107,7 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :nosignatures:
 
     FakeAlgiers
     FakeAlmadenV2

diff --git a/qiskit_ibm_runtime/options/__init__.py b/qiskit_ibm_runtime/options/__init__.py
@@ -57,6 +57,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    EstimatorOptions
    SamplerOptions
@@ -67,6 +68,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    NoiseLearnerOptions
    DynamicalDecouplingOptions

diff --git a/qiskit_ibm_runtime/transpiler/passes/__init__.py b/qiskit_ibm_runtime/transpiler/passes/__init__.py
@@ -23,6 +23,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    ConvertIdToDelay
    ConvertISAToClifford

diff --git a/qiskit_ibm_runtime/transpiler/passes/scheduling/__init__.py b/qiskit_ibm_runtime/transpiler/passes/scheduling/__init__.py
@@ -33,6 +33,7 @@
 =======
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
     BlockBasePadder
     ALAPScheduleAnalysis

diff --git a/qiskit_ibm_runtime/utils/noise_learner_result.py b/qiskit_ibm_runtime/utils/noise_learner_result.py
@@ -17,6 +17,7 @@
 
 .. autosummary::
    :toctree: ../stubs/
+   :nosignatures:
 
    PauliLindbladError
    LayerError

diff --git a/qiskit_ibm_runtime/visualization/__init__.py b/qiskit_ibm_runtime/visualization/__init__.py
@@ -25,6 +25,7 @@
 
 .. autosummary::
     :toctree: ../stubs/
+    :nosignatures:
 
     draw_execution_spans
     draw_layer_error_map

diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -19,8 +19,6 @@ ddt>=1.2.0,!=1.4.0,!=1.4.3
 # Documentation
 nbsphinx
 Sphinx>=6
-sphinx-automodapi
-sphinx-autodoc-typehints<=1.19.2
 jupyter-sphinx
 sphinxcontrib-katex==0.9.9
 packaging