Move API docs for Terra into source (#3085)

* add api docs into terra

* docs to top level

* Add tox target to build documentation

* Add release notes to docs build

* Add docs build to azure

* Remove duplicate deps from docs tox job

* Update codeowners

* Update CONTRIBUTING.md for docs changes

* Remove depth limit from docs job checkout

.github/CODEOWNERS

@@ -6,6 +6,7 @@
 /tools/               @mtreinish @kdk
 /examples/            @jaygambetta @mtreinish @maddy-tod
 test/                 @ajavadia @mtreinish @kdk @1ucian0
+docs/                 @nonhermitian @mtreinish
 
 # Qiskit folders (also their corresponding tests)
 assembler/            @diego-plan @taalexander @mtreinish

CONTRIBUTING.md

@@ -37,9 +37,14 @@ intimate familiarity with qiskit-terra to develop a fix for the issue.
 ### Documentation
 
 If you make a change, make sure you update the associated
-*docstrings* and parts of the
+*docstrings* and parts of the documentation under `docs/apidocs` that
-[documentation](https://github.com/Qiskit/qiskit/tree/master/docs/terra)
+corresponds to it. To locally build the terra specific documentation you
-that corresponds to it. You can also make a [documentation issue](
+can run `tox -edocs` which will compile and build the documentation locally
+and save the output to `docs/_build/html`.
+
+If you have an issue with the combined documentation hosted at
+https://qiskit.org/documentation/ that is maintained in the
+[Qiskit/qiskit](https://github.com/Qiskit/qiskit). You can open a [documentation issue](
 https://github.com/Qiskit/qiskit/issues/new/choose) if you see doc bugs, have a
 new feature that needs to be documented, or think that material could be added
 to the existing docs.
@@ -317,6 +322,13 @@ release and the output will be submitted as a pull request to the documentation
 repository's [release notes file](
 https://github.com/Qiskit/qiskit/blob/master/docs/release_notes.rst)
 
+#### Building release notes locally
+
+Building The release notes are part of the standard qiskit-terra documentation
+builds. To check what the rendered html output of the release notes will look
+like for the current state of the repo you can run: `tox -edocs` which will
+build all the documentation into `docs/_build/html` and the release notes in
+particulare will be located at `docs/_build/html/release_notes.html`
 
 ## Installing Qiskit Terra from source
 Please see the [Installing Qiskit Terra from

azure-pipelines.yml

@@ -182,6 +182,33 @@ stages:
             pylint -rn qiskit test
             reno lint
           displayName: 'Style and lint'
+    - job: 'Docs'
+      pool: {vmImage: 'ubuntu-16.04'}
+      condition: not(startsWith(variables['Build.SourceBranch'], 'refs/tags'))
+      strategy:
+        matrix:
+          Python37:
+            python.version: '3.7'
+      steps:
+        - checkout: self
+        - task: UsePythonVersion@0
+          inputs:
+            versionSpec: '$(python.version)'
+          displayName: 'Use Python $(python.version)'
+        - bash: |
+            set -e
+            python -m pip install --upgrade pip
+            pip install -U tox
+            python setup.py build_ext --inplace
+          displayName: 'Install dependencies'
+        - bash: |
+            tox -edocs -- -j auto
+          displayName: 'Run Docs build'
+        - task: PublishBuildArtifacts@1
+          displayName: 'Publish docs'
+          inputs:
+            pathtoPublish: 'docs/_build/html'
+            artifactName: 'html_docs'
     - job: 'MacOS_HighSierra_Tests'
       pool: {vmImage: 'macOS-10.13'}
       condition: not(startsWith(variables['Build.SourceBranch'], 'refs/tags'))

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/apidocs/assembler.rst

@@ -0,0 +1,13 @@
+.. _qiskit-assembler:
+
+****************
+qiskit.assembler
+****************
+
+.. currentmodule:: qiskit.assembler
+
+
+.. automodapi:: qiskit.assembler
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/circuit/circuit.rst

@@ -0,0 +1,13 @@
+.. _qiskit-circuit:
+
+***************
+qiskit.circuit
+***************
+
+.. currentmodule:: qiskit.circuit
+
+
+.. automodapi:: qiskit.circuit
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/compiler.rst

@@ -0,0 +1,13 @@
+.. _qiskit-compiler:
+
+***************
+qiskit.compiler
+***************
+
+.. currentmodule:: qiskit.compiler
+
+
+.. automodapi:: qiskit.compiler
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/converters.rst

@@ -0,0 +1,13 @@
+.. _qiskit-converters:
+
+*****************
+qiskit.converters
+*****************
+
+.. currentmodule:: qiskit.converters
+
+
+.. automodapi:: qiskit.converters
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/dagcircuit.rst

@@ -0,0 +1,13 @@
+.. _qiskit-dagcircuit:
+
+*****************
+qiskit.dagcircuit
+*****************
+
+.. currentmodule:: qiskit.dagcircuit
+
+
+.. automodapi:: qiskit.dagcircuit
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/execute.rst

@@ -0,0 +1,9 @@
+.. _qiskit-execute:
+
+**************
+qiskit.execute
+**************
+
+.. currentmodule:: qiskit.execute
+
+.. autofunction:: execute

docs/apidocs/extensions/extensions.rst

@@ -0,0 +1,21 @@
+.. _qiskit-extensions:
+
+*****************
+qiskit.extensions
+*****************
+
+.. currentmodule:: qiskit.extensions
+
+
+.. automodapi:: qiskit.extensions
+  :no-heading:
+  :no-inheritance-diagram:
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   simulator
+   standard

docs/apidocs/extensions/simulator.rst

@@ -0,0 +1,13 @@
+.. _qiskit-extensions-simulator:
+
+***************************
+qiskit.extensions.simulator
+***************************
+
+.. currentmodule:: qiskit.extensions.simulator
+
+
+.. automodapi:: qiskit.extensions.simulator
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/extensions/standard.rst

@@ -0,0 +1,13 @@
+.. _qiskit-extensions-standard:
+
+**************************
+qiskit.extensions.standard
+**************************
+
+.. currentmodule:: qiskit.extensions.standard
+
+
+.. automodapi:: qiskit.extensions.standard
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/providers/basicaer.rst

@@ -0,0 +1,13 @@
+.. _qiskit-providers-basicaer:
+
+*************************
+qiskit.providers.basicaer
+*************************
+
+.. currentmodule:: qiskit.providers.basicaer
+
+
+.. automodapi:: qiskit.providers.basicaer
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/providers/models.rst

@@ -0,0 +1,13 @@
+.. _qiskit-providers-models:
+
+***********************
+qiskit.providers.models
+***********************
+
+.. currentmodule:: qiskit.providers.models
+
+
+.. automodapi:: qiskit.providers.models
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/providers/providers.rst

@@ -0,0 +1,22 @@
+.. _qiskit-providers:
+
+****************
+qiskit.providers
+****************
+
+.. currentmodule:: qiskit.providers
+
+
+.. automodapi:: qiskit.providers
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   basicaer
+   models

docs/apidocs/pulse/pulse.rst

@@ -0,0 +1,13 @@
+.. _qiskit-pulse:
+
+************
+qiskit.pulse
+************
+
+.. currentmodule:: qiskit.pulse
+
+
+.. automodapi:: qiskit.pulse
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/qasm.rst

@@ -0,0 +1,13 @@
+.. _qiskit-qasm:
+
+************
+qiskit.qasm
+************
+
+.. currentmodule:: qiskit.qasm
+
+
+.. automodapi:: qiskit.qasm
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/qiskit.rst

@@ -0,0 +1,25 @@
+
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   assembler
+   circuit/circuit
+   compiler
+   converters
+   dagcircuit
+   execute
+   extensions/extensions
+   providers/providers
+   pulse/pulse
+   qasm
+   qobj
+   quantum_info/quantum_info
+   result
+   tools/tools
+   transpiler/transpiler
+   validation
+   visualization/visualization

docs/apidocs/qobj.rst

@@ -0,0 +1,13 @@
+.. _qiskit-qobj:
+
+***********
+qiskit.qobj
+***********
+
+.. currentmodule:: qiskit.qobj
+
+
+.. automodapi:: qiskit.qobj
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/quantum_info/quantum_info.rst

@@ -0,0 +1,20 @@
+.. _qiskit-quantum_info:
+
+*******************
+qiskit.quantum_info
+*******************
+
+.. currentmodule:: qiskit.quantum_info
+
+
+.. automodapi:: qiskit.quantum_info
+  :no-heading:
+  :no-inheritance-diagram:
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   synthesis/synthesis

docs/apidocs/quantum_info/synthesis/synthesis.rst

@@ -0,0 +1,13 @@
+.. _qiskit-quantum_info-synthesis:
+
+*****************************
+qiskit.quantum_info.synthesis
+*****************************
+
+.. currentmodule:: qiskit.quantum_info.synthesis
+
+
+.. automodapi:: qiskit.quantum_info.synthesis
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/result.rst

@@ -0,0 +1,13 @@
+.. _qiskit-result:
+
+*************
+qiskit.result
+*************
+
+.. currentmodule:: qiskit.result
+
+
+.. automodapi:: qiskit.result
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/tools/events/events.rst

@@ -0,0 +1,13 @@
+.. _qiskit-tools-events:
+
+*******************
+qiskit.tools.events
+*******************
+
+.. currentmodule:: qiskit.tools.events
+
+
+.. automodapi:: qiskit.tools.events
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/tools/monitor/monitor.rst

@@ -0,0 +1,13 @@
+.. _qiskit-tools-monitor:
+
+********************
+qiskit.tools.monitor
+********************
+
+.. currentmodule:: qiskit.tools.monitor
+
+
+.. automodapi:: qiskit.tools.monitor
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/tools/qi/qi.rst

@@ -0,0 +1,13 @@
+.. _qiskit-tools-qi:
+
+***************
+qiskit.tools.qi
+***************
+
+.. currentmodule:: qiskit.tools.qi
+
+
+.. automodapi:: qiskit.tools.qi
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/tools/tools.rst

@@ -0,0 +1,24 @@
+.. _qiskit-tools:
+
+************
+qiskit.tools
+************
+
+.. currentmodule:: qiskit.tools
+
+
+.. automodapi:: qiskit.tools
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:
+
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   events/events
+   monitor/monitor
+   qi/qi

docs/apidocs/transpiler/passes/mapping/mapping.rst

@@ -0,0 +1,13 @@
+.. _qiskit-transpiler-mapping:
+
+********************************
+qiskit.transpiler.passes.mapping
+********************************
+
+.. currentmodule:: qiskit.transpiler.passes.mapping
+
+
+.. automodapi:: qiskit.transpiler.passes.mapping
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/transpiler/passes/passes.rst

@@ -0,0 +1,21 @@
+.. _qiskit-transpiler-passes:
+
+************************
+qiskit.transpiler.passes
+************************
+
+.. currentmodule:: qiskit.transpiler.passes
+
+
+.. automodapi:: qiskit.transpiler.passes
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   mapping/mapping

docs/apidocs/transpiler/preset_passmanagers/preset_passmanagers.rst

@@ -0,0 +1,13 @@
+.. _qiskit-transpiler-preset-passmanagers:
+
+*************************************
+qiskit.transpiler.preset_passmanagers
+*************************************
+
+.. currentmodule:: qiskit.transpiler.preset_passmanagers
+
+
+.. automodapi:: qiskit.transpiler.preset_passmanagers
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/transpiler/transpiler.rst

@@ -0,0 +1,22 @@
+.. _qiskit-transpiler:
+
+*****************
+qiskit.transpiler
+*****************
+
+.. currentmodule:: qiskit.transpiler
+
+
+.. automodapi:: qiskit.transpiler
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   passes/passes
+   preset_passmanagers/preset_passmanagers

docs/apidocs/validation.rst

@@ -0,0 +1,13 @@
+.. _qiskit-validation:
+
+*****************
+qiskit.validation
+*****************
+
+.. currentmodule:: qiskit.validation
+
+
+.. automodapi:: qiskit.validation
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/visualization/interactive/interactive.rst

@@ -0,0 +1,13 @@
+.. _qiskit-visualization-interactive:
+
+********************************
+qiskit.visualization.interactive
+********************************
+
+.. currentmodule:: qiskit.visualization.interactive
+
+
+.. automodapi:: qiskit.visualization.interactive
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:

docs/apidocs/visualization/visualization.rst

@@ -0,0 +1,22 @@
+.. _qiskit-visualization:
+
+********************
+qiskit.visualization
+********************
+
+.. currentmodule:: qiskit.visualization
+
+
+.. automodapi:: qiskit.visualization
+  :no-heading:
+  :no-inheritance-diagram:
+  :inherited-members:
+
+
+Submodules
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   interactive/interactive

docs/conf.py

@@ -0,0 +1,117 @@
+# -*- coding: utf-8 -*-
+
+# 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
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# 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('.'))
+
+"""
+Sphinx documentation builder
+"""
+
+# -- Project information -----------------------------------------------------
+project = 'Qiskit'
+copyright = '2019, Qiskit Development Team'  # pylint: disable=redefined-builtin
+author = 'Qiskit Development Team'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = '0.12.0'
+
+# -- 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.autodoc',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.extlinks',
+    'sphinx_tabs.tabs',
+    'sphinx_automodapi.automodapi',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'IPython.sphinxext.ipython_directive',
+    'reno.sphinxext',
+]
+
+
+# If true, figures, tables and code-blocks are automatically numbered 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'
+}
+# 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
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+# 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.
+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).
+# This can be handy if you document a project that consists of a single
+# 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
+
+
+# -- 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 = 'sphinx_rtd_theme'  # use the theme in subdir 'theme'
+
+html_sidebars = {'**': ['globaltoc.html']}
+html_last_updated_fmt = '%Y/%m/%d'

docs/index.rst

@@ -0,0 +1,15 @@
+##########################
+Qiskit Terra documentation
+##########################
+
+.. toctree::
+  :maxdepth: 2
+  :hidden:
+
+  API References <apidocs/qiskit>
+  Release Notes <release_notes>
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`

docs/release_notes.rst

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

requirements-dev.txt

@@ -18,3 +18,7 @@ pylatexenc>=1.4
 ddt>=1.2.0
 seaborn>=0.9.0
 reno>=2.11.0
+Sphinx>=1.8.3
+sphinx-rtd-theme>=0.4.0
+sphinx-tabs>=1.1.11 
+sphinx-automodapi

tox.ini

@@ -31,3 +31,9 @@ commands =
   stestr run {posargs}
   coverage3 combine
   coverage3 report
+
+[testenv:docs]
+deps =
+  -r{toxinidir}/requirements-dev.txt
+commands =
+  sphinx-build -b html docs/ docs/_build/html {posargs}