Tweak docs config from Qiskit/qiskit#6855

docs/_templates/autosummary/class.rst

@@ -0,0 +1,41 @@
+{#
+   The general principle of this is that we manually document attributes here in
+   the same file, but give all methods their own page.  By default, we document
+   all methods, including those defined by parent classes.
+-#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+{#-
+   Avoid having autodoc populate the class with the members we're about to
+   summarize to avoid duplication.
+#}
+   :no-members:
+   :show-inheritance:
+{#
+   Methods all get their own separate page, with their names and the first lines
+   of their docstrings tabulated.  The documentation from `__init__` is
+   automatically included in the standard class documentation, so we don't want
+   to repeat it.
+-#}
+{% block methods_summary %}{% set wanted_methods = (methods | reject('==', '__init__') | list) %}{% if wanted_methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+      :nosignatures:
+      :toctree: ../stubs/
+{% for item in wanted_methods %}
+      ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}{% endblock %}
+
+{% block attributes_summary %}{% if attributes %}
+   .. rubric:: Attributes
+{# Attributes should all be summarized directly on the same page. -#}
+{% for item in attributes %}
+   .. autoattribute:: {{ item }}
+{%- endfor %}
+{% endif %}{% endblock -%}

docs/_templates/autosummary/class_no_inherited_members.rst

@@ -0,0 +1,38 @@
+{#
+   This is very similar to the default class template, except this one is used
+   when we don't want to generate any inherited methods.
+-#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+{#-
+   Avoid having autodoc populate the class with the members we're about to
+   summarize to avoid duplication.
+#}
+   :no-members:
+   :show-inheritance:
+{#
+   Methods all get their own separate page, with their names and the first lines
+   of their docstrings tabulated.
+-#}
+{% block methods_summary %}{% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %}{% if wanted_methods %}
+   .. rubric:: Methods Defined Here
+
+   .. autosummary::
+      :nosignatures:
+      :toctree: ../stubs/
+{% for item in wanted_methods %}
+      ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}{% endblock %}
+
+{% block attributes_summary %}{% if attributes %}
+   .. rubric:: Attributes
+{# Attributes should all be summarized directly on the same page. -#}
+{% for item in attributes %}
+   .. autoattribute:: {{ item }}
+{%- endfor %}
+{% endif %}{% endblock -%}

docs/conf.py

@@ -18,12 +18,6 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
 import sys
 sys.path.insert(0, os.path.abspath('.'))
@@ -33,14 +27,15 @@
                                CustomGalleryItemDirective, CustomCalloutItemDirective,
                                CustomCardItemDirective)
 
-# -- Project information -----------------------------------------------------
 from distutils import dir_util
 import re
 import shutil
 import subprocess
 import tempfile
 import warnings
 
+# -- General configuration ---------------------------------------------------
+
 project = 'Qiskit'
 copyright = '2021, Qiskit Development Team'
 author = 'Qiskit Development Team'
@@ -54,22 +49,14 @@
 .. |version| replace:: {0}
 """.format(release)
 
-# -- General configuration ---------------------------------------------------
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
 extensions = [
+    'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
+    "sphinx.ext.autosummary",
     'sphinx.ext.mathjax',
-    'sphinx.ext.napoleon',
-    'sphinx_autodoc_typehints',
     'sphinx.ext.viewcode',
     'sphinx.ext.extlinks',
-    'sphinx_automodapi.automodapi',
+    'sphinx_autodoc_typehints',
     'jupyter_sphinx',
     'nbsphinx',
     'sphinx_panels',
@@ -121,9 +108,6 @@
     'index.html'
 ]
 
-# -----------------------------------------------------------------------------
-# Redirects
-# ----------------------------------------------------------------------------- 
 redirects = {
     "install": "getting_started.html",
 }
@@ -179,32 +163,17 @@
     "tabs-color-label-active": "rgb(138, 63, 252)",
     "tabs-color-label-inactive": "rgb(221, 225, 230)",
 }
+templates_path = ['_templates']
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['theme/']
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
-
-# The master toctree document.
 master_doc = 'index'
 
-# If true, figures, tables and code-blocks are automatically numbered if they
-# have a caption.
+# Number figures, tables and code-blocks if they have a caption.
 numfig = True
-
-# A dictionary mapping 'figure', 'table', 'code-block' and 'section' to
-# strings that are used for format of figure numbers. As a special character,
-# %s will be replaced to figure number.
-numfig_format = {
-    'table': 'Table %s'
-}
+# Available keys are 'figure', 'table', 'code-block' and 'section'.  '%s' is    the number.
+numfig_format = {'table': 'Table %s'}
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = None
@@ -213,12 +182,9 @@
 locale_dirs = ['locale/']   # path is example but recommended.
 gettext_compact = False     # optional.
 
-# The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'colorful'
 
-# A boolean that decides whether module names are prepended to all object names
-# (for object types where a “module” of some kind is defined), e.g. for
-# py:function directives.
+# Whether module names are included in crossrefs of functions, classes, etc.
 add_module_names = False
 
 # A list of prefixes that are ignored for sorting the Python module index
@@ -227,9 +193,10 @@
 # package. Works only for the HTML builder currently.
 modindex_common_prefix = ['qiskit.']
 
+
+
 # -- Configuration for extlinks extension ------------------------------------
 # Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
-
 extlinks = {
     'pull_terra': ('https://github.com/Qiskit/qiskit-terra/pull/%s', '#'),
     'pull_aqua': ('https://github.com/Qiskit/qiskit-aqua/pull/%s', '#'),
@@ -240,17 +207,7 @@
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "qiskit_sphinx_theme"
-
-html_theme_path = ['.', qiskit_sphinx_theme.get_html_theme_path()]
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
 html_theme_options = {
     'logo_only': False,
     'display_version': True,
@@ -263,27 +220,20 @@
     'includehidden': True,
     'titles_only': False,
 }
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-templates_path = ['_templates']
 html_css_files = ['custom.css', 'gallery.css']
-
 html_favicon = 'images/favicon.ico'
-
 html_last_updated_fmt = '%Y/%m/%d'
 
+# -- Options for Autosummary and Autodoc ------------------------------------
+# Note that setting autodoc defaults here may not have as much of an effect as  you may expect; any
+# documentation created by autosummary uses a template file (in autosummary in  the templates path),
+# which likely overrides the autodoc defaults.
 autosummary_generate = True
 autosummary_generate_overwrite = False
-
-autodoc_default_options = {
-    'inherited-members': None,
-}
-
 autoclass_content = 'both'
-# -- Extension configuration -------------------------------------------------
+
+# --- Custom Extensions -----------------------------------------------------
 
 # Elements with api doc sources
 qiskit_elements = ['qiskit-terra', 'qiskit-aer', 'qiskit-ignis',