From 7c5e87c8d3ac97c3aeb8a80b13dabed94adeb462 Mon Sep 17 00:00:00 2001 From: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> Date: Mon, 25 Nov 2024 10:46:51 -0500 Subject: [PATCH] Fix type hints in docs for PUBs and improve Sphinx config (#2052) Closes https://github.com/Qiskit/qiskit-ibm-runtime/issues/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 https://github.com/Qiskit/documentation/issues/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 ``` Return the execution mode used by this primitive. ``` You could rewrite to say ``` Return the execution mode used by this primitive, either :class:~`.Session` or ~:class:~`.Batch`. ``` --- docs/_templates/autosummary/base.rst | 10 ---------- docs/_templates/autosummary/class.rst | 15 ++++++++------- docs/apidocs/index.rst | 6 +++--- docs/conf.py | 15 +++++++++++---- qiskit_ibm_runtime/__init__.py | 1 + qiskit_ibm_runtime/debug_tools/__init__.py | 1 + qiskit_ibm_runtime/execution_span/__init__.py | 1 + qiskit_ibm_runtime/fake_provider/__init__.py | 2 ++ qiskit_ibm_runtime/options/__init__.py | 2 ++ qiskit_ibm_runtime/transpiler/passes/__init__.py | 1 + .../transpiler/passes/scheduling/__init__.py | 1 + qiskit_ibm_runtime/utils/noise_learner_result.py | 1 + qiskit_ibm_runtime/visualization/__init__.py | 1 + requirements-dev.txt | 2 -- 14 files changed, 33 insertions(+), 26 deletions(-) delete mode 100644 docs/_templates/autosummary/base.rst diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst deleted file mode 100644 index a58aa35ff..000000000 --- a/docs/_templates/autosummary/base.rst +++ /dev/null @@ -1,10 +0,0 @@ -{% if referencefile %} -.. include:: {{ referencefile }} -{% endif %} - -{{ objname }} -{{ underline }} - -.. currentmodule:: {{ module }} - -.. auto{{ objtype }}:: {{ objname }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 471c0f6c8..db80618d9 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -1,9 +1,9 @@ -{% 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 }} @@ -11,13 +11,14 @@ :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 index e90dc0e0b..efdbb0c0c 100644 --- 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 index acdda859b..9038fec3d 100644 --- 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 index 80c200a90..c2dfab545 100644 --- 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 index ca86bc95b..59924869f 100644 --- 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 index 49d891b25..c5a26d7be 100644 --- 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 index 3d76ccc95..4760fbb07 100644 --- 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 index ab043b4fa..a93e6f675 100644 --- 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 index 03f1a4306..cf394fbe9 100644 --- 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 index 2ae3259c0..90f1b9a13 100644 --- 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 index 334c784b8..184086962 100644 --- 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 index e0ccf5681..b587c9100 100644 --- 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 index fac6e7127..2ffd70c70 100644 --- 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