From 159ea777681d9f50adc2b6700ae3b8c6f0c6e561 Mon Sep 17 00:00:00 2001 From: Paul Nation Date: Mon, 30 Sep 2019 12:50:44 -0400 Subject: [PATCH] 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 | 1 + CONTRIBUTING.md | 18 ++- azure-pipelines.yml | 27 ++++ docs/Makefile | 28 +++++ docs/apidocs/assembler.rst | 13 ++ docs/apidocs/circuit/circuit.rst | 13 ++ docs/apidocs/compiler.rst | 13 ++ docs/apidocs/converters.rst | 13 ++ docs/apidocs/dagcircuit.rst | 13 ++ docs/apidocs/execute.rst | 9 ++ docs/apidocs/extensions/extensions.rst | 21 ++++ docs/apidocs/extensions/simulator.rst | 13 ++ docs/apidocs/extensions/standard.rst | 13 ++ docs/apidocs/providers/basicaer.rst | 13 ++ docs/apidocs/providers/models.rst | 13 ++ docs/apidocs/providers/providers.rst | 22 ++++ docs/apidocs/pulse/pulse.rst | 13 ++ docs/apidocs/qasm.rst | 13 ++ docs/apidocs/qiskit.rst | 25 ++++ docs/apidocs/qobj.rst | 13 ++ docs/apidocs/quantum_info/quantum_info.rst | 20 +++ .../quantum_info/synthesis/synthesis.rst | 13 ++ docs/apidocs/result.rst | 13 ++ docs/apidocs/tools/events/events.rst | 13 ++ docs/apidocs/tools/monitor/monitor.rst | 13 ++ docs/apidocs/tools/qi/qi.rst | 13 ++ docs/apidocs/tools/tools.rst | 24 ++++ .../transpiler/passes/mapping/mapping.rst | 13 ++ docs/apidocs/transpiler/passes/passes.rst | 21 ++++ .../preset_passmanagers.rst | 13 ++ docs/apidocs/transpiler/transpiler.rst | 22 ++++ docs/apidocs/validation.rst | 13 ++ .../visualization/interactive/interactive.rst | 13 ++ docs/apidocs/visualization/visualization.rst | 22 ++++ docs/conf.py | 117 ++++++++++++++++++ docs/index.rst | 15 +++ docs/release_notes.rst | 1 + requirements-dev.txt | 6 +- tox.ini | 6 + 39 files changed, 674 insertions(+), 4 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/apidocs/assembler.rst create mode 100644 docs/apidocs/circuit/circuit.rst create mode 100644 docs/apidocs/compiler.rst create mode 100644 docs/apidocs/converters.rst create mode 100644 docs/apidocs/dagcircuit.rst create mode 100644 docs/apidocs/execute.rst create mode 100644 docs/apidocs/extensions/extensions.rst create mode 100644 docs/apidocs/extensions/simulator.rst create mode 100644 docs/apidocs/extensions/standard.rst create mode 100644 docs/apidocs/providers/basicaer.rst create mode 100644 docs/apidocs/providers/models.rst create mode 100644 docs/apidocs/providers/providers.rst create mode 100644 docs/apidocs/pulse/pulse.rst create mode 100644 docs/apidocs/qasm.rst create mode 100644 docs/apidocs/qiskit.rst create mode 100644 docs/apidocs/qobj.rst create mode 100644 docs/apidocs/quantum_info/quantum_info.rst create mode 100644 docs/apidocs/quantum_info/synthesis/synthesis.rst create mode 100644 docs/apidocs/result.rst create mode 100644 docs/apidocs/tools/events/events.rst create mode 100644 docs/apidocs/tools/monitor/monitor.rst create mode 100644 docs/apidocs/tools/qi/qi.rst create mode 100644 docs/apidocs/tools/tools.rst create mode 100644 docs/apidocs/transpiler/passes/mapping/mapping.rst create mode 100644 docs/apidocs/transpiler/passes/passes.rst create mode 100644 docs/apidocs/transpiler/preset_passmanagers/preset_passmanagers.rst create mode 100644 docs/apidocs/transpiler/transpiler.rst create mode 100644 docs/apidocs/validation.rst create mode 100644 docs/apidocs/visualization/interactive/interactive.rst create mode 100644 docs/apidocs/visualization/visualization.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/release_notes.rst diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c05420f4d4..ed0254bb0e 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcc7fcd098..ec0004e370 100644 --- a/CONTRIBUTING.md +++ b/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 -[documentation](https://github.com/Qiskit/qiskit/tree/master/docs/terra) -that corresponds to it. You can also make a [documentation issue]( +*docstrings* and parts of the documentation under `docs/apidocs` that +corresponds to it. To locally build the terra specific documentation you +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 diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 857996558b..da7faf3378 100644 --- a/azure-pipelines.yml +++ b/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')) diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000..dce383c937 --- /dev/null +++ b/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) diff --git a/docs/apidocs/assembler.rst b/docs/apidocs/assembler.rst new file mode 100644 index 0000000000..1610042759 --- /dev/null +++ b/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: diff --git a/docs/apidocs/circuit/circuit.rst b/docs/apidocs/circuit/circuit.rst new file mode 100644 index 0000000000..47614fa52b --- /dev/null +++ b/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: diff --git a/docs/apidocs/compiler.rst b/docs/apidocs/compiler.rst new file mode 100644 index 0000000000..5d85e38af8 --- /dev/null +++ b/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: diff --git a/docs/apidocs/converters.rst b/docs/apidocs/converters.rst new file mode 100644 index 0000000000..2e608a7678 --- /dev/null +++ b/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: diff --git a/docs/apidocs/dagcircuit.rst b/docs/apidocs/dagcircuit.rst new file mode 100644 index 0000000000..f762f8185f --- /dev/null +++ b/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: diff --git a/docs/apidocs/execute.rst b/docs/apidocs/execute.rst new file mode 100644 index 0000000000..78c5a52d61 --- /dev/null +++ b/docs/apidocs/execute.rst @@ -0,0 +1,9 @@ +.. _qiskit-execute: + +************** +qiskit.execute +************** + +.. currentmodule:: qiskit.execute + +.. autofunction:: execute diff --git a/docs/apidocs/extensions/extensions.rst b/docs/apidocs/extensions/extensions.rst new file mode 100644 index 0000000000..fe07699ced --- /dev/null +++ b/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 diff --git a/docs/apidocs/extensions/simulator.rst b/docs/apidocs/extensions/simulator.rst new file mode 100644 index 0000000000..8563799828 --- /dev/null +++ b/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: diff --git a/docs/apidocs/extensions/standard.rst b/docs/apidocs/extensions/standard.rst new file mode 100644 index 0000000000..d4578a9b76 --- /dev/null +++ b/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: diff --git a/docs/apidocs/providers/basicaer.rst b/docs/apidocs/providers/basicaer.rst new file mode 100644 index 0000000000..9ab59929ef --- /dev/null +++ b/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: diff --git a/docs/apidocs/providers/models.rst b/docs/apidocs/providers/models.rst new file mode 100644 index 0000000000..ff6f9e7c05 --- /dev/null +++ b/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: diff --git a/docs/apidocs/providers/providers.rst b/docs/apidocs/providers/providers.rst new file mode 100644 index 0000000000..fbd838a874 --- /dev/null +++ b/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 diff --git a/docs/apidocs/pulse/pulse.rst b/docs/apidocs/pulse/pulse.rst new file mode 100644 index 0000000000..870e58de00 --- /dev/null +++ b/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: diff --git a/docs/apidocs/qasm.rst b/docs/apidocs/qasm.rst new file mode 100644 index 0000000000..978e97f7c2 --- /dev/null +++ b/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: diff --git a/docs/apidocs/qiskit.rst b/docs/apidocs/qiskit.rst new file mode 100644 index 0000000000..7ec6e33787 --- /dev/null +++ b/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 diff --git a/docs/apidocs/qobj.rst b/docs/apidocs/qobj.rst new file mode 100644 index 0000000000..f8739b8037 --- /dev/null +++ b/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: diff --git a/docs/apidocs/quantum_info/quantum_info.rst b/docs/apidocs/quantum_info/quantum_info.rst new file mode 100644 index 0000000000..40fd349151 --- /dev/null +++ b/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 diff --git a/docs/apidocs/quantum_info/synthesis/synthesis.rst b/docs/apidocs/quantum_info/synthesis/synthesis.rst new file mode 100644 index 0000000000..ed9add81dd --- /dev/null +++ b/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: diff --git a/docs/apidocs/result.rst b/docs/apidocs/result.rst new file mode 100644 index 0000000000..0815bd7082 --- /dev/null +++ b/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: diff --git a/docs/apidocs/tools/events/events.rst b/docs/apidocs/tools/events/events.rst new file mode 100644 index 0000000000..586f786c8f --- /dev/null +++ b/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: diff --git a/docs/apidocs/tools/monitor/monitor.rst b/docs/apidocs/tools/monitor/monitor.rst new file mode 100644 index 0000000000..eab6edec7c --- /dev/null +++ b/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: diff --git a/docs/apidocs/tools/qi/qi.rst b/docs/apidocs/tools/qi/qi.rst new file mode 100644 index 0000000000..4429b4c3a8 --- /dev/null +++ b/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: diff --git a/docs/apidocs/tools/tools.rst b/docs/apidocs/tools/tools.rst new file mode 100644 index 0000000000..97c53bfb2a --- /dev/null +++ b/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 diff --git a/docs/apidocs/transpiler/passes/mapping/mapping.rst b/docs/apidocs/transpiler/passes/mapping/mapping.rst new file mode 100644 index 0000000000..23310df98d --- /dev/null +++ b/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: diff --git a/docs/apidocs/transpiler/passes/passes.rst b/docs/apidocs/transpiler/passes/passes.rst new file mode 100644 index 0000000000..a1b0690074 --- /dev/null +++ b/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 diff --git a/docs/apidocs/transpiler/preset_passmanagers/preset_passmanagers.rst b/docs/apidocs/transpiler/preset_passmanagers/preset_passmanagers.rst new file mode 100644 index 0000000000..6d231e1009 --- /dev/null +++ b/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: diff --git a/docs/apidocs/transpiler/transpiler.rst b/docs/apidocs/transpiler/transpiler.rst new file mode 100644 index 0000000000..48edf436f9 --- /dev/null +++ b/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 diff --git a/docs/apidocs/validation.rst b/docs/apidocs/validation.rst new file mode 100644 index 0000000000..05ada94dbe --- /dev/null +++ b/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: diff --git a/docs/apidocs/visualization/interactive/interactive.rst b/docs/apidocs/visualization/interactive/interactive.rst new file mode 100644 index 0000000000..8607628327 --- /dev/null +++ b/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: diff --git a/docs/apidocs/visualization/visualization.rst b/docs/apidocs/visualization/visualization.rst new file mode 100644 index 0000000000..55017a5423 --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..509870b102 --- /dev/null +++ b/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' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..9b256d73dc --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,15 @@ +########################## +Qiskit Terra documentation +########################## + +.. toctree:: + :maxdepth: 2 + :hidden: + + API References + Release Notes + +.. Hiding - Indices and tables + :ref:`genindex` + :ref:`modindex` + :ref:`search` diff --git a/docs/release_notes.rst b/docs/release_notes.rst new file mode 100644 index 0000000000..ec77acc34c --- /dev/null +++ b/docs/release_notes.rst @@ -0,0 +1 @@ +.. release-notes:: Release Notes diff --git a/requirements-dev.txt b/requirements-dev.txt index ec34bb45f4..a9707c79d5 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -17,4 +17,8 @@ pillow>=4.2.1 pylatexenc>=1.4 ddt>=1.2.0 seaborn>=0.9.0 -reno>=2.11.0 \ No newline at end of file +reno>=2.11.0 +Sphinx>=1.8.3 +sphinx-rtd-theme>=0.4.0 +sphinx-tabs>=1.1.11 +sphinx-automodapi \ No newline at end of file diff --git a/tox.ini b/tox.ini index 8700fd838f..0b1a1007c9 100644 --- a/tox.ini +++ b/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}