Add docs infrastructure

docs/Makefile

@@ -0,0 +1,28 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/autosummary/class.rst

@@ -0,0 +1,31 @@
+{#
+   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 | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

docs/_templates/autosummary/class_no_inherited_members.rst

@@ -0,0 +1,28 @@
+{# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

docs/apidocs/algorithms.rst

@@ -0,0 +1,6 @@
+.. _qiskit-algorithms:
+
+.. automodule:: qiskit_algorithms
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/conf.py

@@ -0,0 +1,124 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# pylint: disable=invalid-name
+
+"""Sphinx documentation builder."""
+
+# -- General configuration ---------------------------------------------------
+import datetime
+import doctest
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+sys.path.append(os.path.abspath("."))
+
+project = "Qiskit Algorithms"
+copyright = f"2017-{datetime.date.today().year}, Qiskit Algorithms Development Team" # pylint: disable=redefined-builtin
+author = "Qiskit Algorithms Development Team"
+
+# The short X.Y version
+version = "0.1"
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.doctest",
+    "reno.sphinxext",
+    "sphinx_design",
+    "matplotlib.sphinxext.plot_directive",
+    "sphinx.ext.doctest"
+]
+
+templates_path = ["_templates"]
+
+# Number figures, tables and code-blocks if they have a caption.
+numfig = True
+# 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 or the default for gettext content translation.
+language = "en"
+
+# Relative to source directory, affects general discovery, and html_static_path and html_extra_path.
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+
+pygments_style = "colorful"
+
+# 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
+# (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F).
+modindex_common_prefix = ["qiskit."]
+
+intersphinx_mapping = {
+    "rustworkx": ("https://qiskit.org/ecosystem/rustworkx/", None),
+    "qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None),
+    "qiskit-aer": ("https://qiskit.org/ecosystem/aer/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = "qiskit_sphinx_theme"
+html_last_updated_fmt = "%Y/%m/%d"
+html_theme_options = {
+    "logo_only": True,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": True,
+}
+
+
+# -- 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.
+
+# Move type hints from signatures to the parameter descriptions (except in overload cases, where
+# that's not possible).
+autodoc_typehints = "description"
+# Only add type hints from signature to description body if the parameter has documentation.  The
+# return type is always added to the description (if in the signature).
+autodoc_typehints_description_target = "documented_params"
+
+autosummary_generate = True
+autosummary_generate_overwrite = False
+autoclass_content = "both"
+
+
+# -- Options for Doctest --------------------------------------------------------
+
+doctest_default_flags = (
+    doctest.ELLIPSIS
+    | doctest.NORMALIZE_WHITESPACE
+    | doctest.IGNORE_EXCEPTION_DETAIL
+    | doctest.DONT_ACCEPT_TRUE_FOR_1
+)
+
+# Leaving this string empty disables testing of doctest blocks from docstrings.
+# Doctest blocks are structures like this one:
+# >> code
+# output
+doctest_test_doctest_blocks = ""

docs/index.rst

@@ -0,0 +1,17 @@
+################################
+Qiskit Algorithms documentation
+################################
+
+
+.. toctree::
+  :hidden:
+
+  API References <apidocs/algorithms>
+  Tutorials <tutorials/index>
+  Release Notes <release_notes>
+  GitHub <https://github.com/qiskit-community/qiskit-algorithms>
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`

docs/release_notes.rst

@@ -0,0 +1 @@
+.. release-notes:: Release Notes