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

Eric-Arellano · web-flow · commit 7c5e87c8d3ac · 2024-11-25T10:46:51.000-05:00
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`. ```
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
