diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 000000000000..5b3ebf3bdf03 --- /dev/null +++ b/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 -%} diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst new file mode 100644 index 000000000000..6cde3cf5328d --- /dev/null +++ b/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 -%} diff --git a/docs/conf.py b/docs/conf.py index 8841a1decd5d..b9949d5b2245 100644 --- a/docs/conf.py +++ b/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,7 +27,6 @@ CustomGalleryItemDirective, CustomCalloutItemDirective, CustomCardItemDirective) -# -- Project information ----------------------------------------------------- from distutils import dir_util import re import shutil @@ -41,6 +34,8 @@ 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',