Improve Sphinx config for autodoc and autosummary (Cherry-pick of #132)…

… (#133)

Improve Sphinx config for autodoc and autosummary (#132)

While adding the new Qiskit addons, the docs team iterated on how best to configure Sphinx for more useful docs. You can see the result of this change at Qiskit/documentation#2342.

docs/_templates/autosummary/class.rst

@@ -9,13 +9,14 @@
 
 .. autoclass:: {{ objname }}
    :no-members:
+   :no-inherited-members:
+   :no-special-members:
    :show-inheritance:
 
 {% block attributes_summary %}
-  {% set wanted_attributes = (attributes | reject('in', inherited_members) | list) %}
-  {% if wanted_attributes %}
+  {% if attributes %}
    .. rubric:: Attributes
-    {% for item in wanted_attributes %}
+    {% for item in attributes %}
    .. autoattribute:: {{ item }}
     {%- endfor %}
   {% endif %}
@@ -29,4 +30,4 @@
    .. automethod:: {{ item }}
     {%- endfor %}
   {% endif %}
-{% endblock %}
+{% endblock %}

docs/apidocs/index.rst

@@ -1,5 +1,5 @@
 ***************************************
-qiskit-ibm-transpiler API reference
+``qiskit-ibm-transpiler`` API reference
 ***************************************
 
 .. toctree::

docs/conf.py

@@ -30,9 +30,17 @@
     "qiskit_sphinx_theme",
 ]
 
-# Move type hints from signatures to the parameter descriptions (except in overload cases, where
-# that's not possible).
+# Options for autodoc. These reflect the values from Qiskit SDK and Runtime.
+autosummary_generate = True
+autosummary_generate_overwrite = False
+autoclass_content = "both"
 autodoc_typehints = "description"
+autodoc_default_options = {
+    "inherited-members": None,
+    "show-inheritance": True,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]