diff --git a/.gitignore b/.gitignore index 1a645c41440f..f97eea26d89e 100644 --- a/.gitignore +++ b/.gitignore @@ -140,3 +140,6 @@ src/qasm-simulator-cpp/test/qubit_vector_tests # Cython pass qiskit/transpiler/passes/**/cython/**/*.cpp + +docs/api/* +docs/stubs/* diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 000000000000..84980a3a4a60 --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,12 @@ +.wy-nav-content { + max-width: 90% !important; +} + +.wy-side-scroll { + background:#8c8c8c; +} + +.pre +{ +color:#BE8184; +} diff --git a/docs/apidocs/qiskit.rst b/docs/apidocs/qiskit.rst index 7ec6e33787f0..62447593c352 100644 --- a/docs/apidocs/qiskit.rst +++ b/docs/apidocs/qiskit.rst @@ -1,3 +1,4 @@ +.. module:: qiskit ============= API Reference @@ -22,4 +23,4 @@ API Reference tools/tools transpiler/transpiler validation - visualization/visualization + visualization diff --git a/docs/apidocs/visualization.rst b/docs/apidocs/visualization.rst new file mode 100644 index 000000000000..4dcc8b7c076e --- /dev/null +++ b/docs/apidocs/visualization.rst @@ -0,0 +1,6 @@ +.. _qiskit-visualization: + +.. automodule:: qiskit.visualization + :no-members: + :no-inherited-members: + :no-special-members: diff --git a/docs/apidocs/visualization/interactive/interactive.rst b/docs/apidocs/visualization/interactive/interactive.rst deleted file mode 100644 index 860762832720..000000000000 --- a/docs/apidocs/visualization/interactive/interactive.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _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 deleted file mode 100644 index 55017a5423ee..000000000000 --- a/docs/apidocs/visualization/visualization.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _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 index 509870b102b4..a196960fbf5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,11 @@ Sphinx documentation builder """ +import os +# Set env flag so that we can doc functions that may otherwise not be loaded +# see for example interactive visualizations in qiskit.visualization. +os.environ['QISKIT_DOCS'] = 'TRUE' + # -- Project information ----------------------------------------------------- project = 'Qiskit' copyright = '2019, Qiskit Development Team' # pylint: disable=redefined-builtin @@ -53,17 +58,35 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx_automodapi.automodapi', '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', + 'jupyter_sphinx.execute', 'reno.sphinxext', ] +html_static_path = ['_static'] +html_css_files = [ + 'style.css', +] + +# ----------------------------------------------------------------------------- +# Autosummary +# ----------------------------------------------------------------------------- + +autosummary_generate = True + +# ----------------------------------------------------------------------------- +# Autodoc +# ----------------------------------------------------------------------------- + +autodoc_default_options = { + 'inherited-members': None, +} # If true, figures, tables and code-blocks are automatically numbered if they @@ -89,7 +112,7 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = None +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 @@ -113,5 +136,15 @@ # html_theme = 'sphinx_rtd_theme' # use the theme in subdir 'theme' -html_sidebars = {'**': ['globaltoc.html']} +html_logo = 'images/logo.png' +#html_sidebars = {'**': ['globaltoc.html']} 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, + 'style_nav_header_background': '#212121', +} + diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 000000000000..c4f83672e404 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/qiskit/visualization/__init__.py b/qiskit/visualization/__init__.py index f18702b5d4b4..b0ab31e91791 100644 --- a/qiskit/visualization/__init__.py +++ b/qiskit/visualization/__init__.py @@ -12,8 +12,85 @@ # copyright notice, and modified files need to carry a notice indicating # that they have been altered from the originals. -"""Main Qiskit visualization methods.""" +""" +============================================ +Visualizations (:mod:`qiskit.visualization`) +============================================ +.. currentmodule:: qiskit.visualization + +Counts and State Visualizations +=============================== + +.. autosummary:: + :toctree: ../stubs/ + + plot_histogram + plot_bloch_vector + plot_bloch_multivector + plot_state_city + plot_state_hinton + plot_state_paulivec + plot_state_qsphere + +Interactive Visualizations +========================== + +.. autosummary:: + :toctree: ../stubs/ + + iplot_histogram + iplot_bloch_multivector + iplot_state_city + iplot_state_hinton + iplot_state_paulivec + iplot_state_qsphere + +Device Visualizations +===================== + +.. autosummary:: + :toctree: ../stubs/ + + plot_gate_map + plot_error_map + plot_circuit_layout + +Circuit Visualizations +====================== + +.. autosummary:: + :toctree: ../stubs/ + + circuit_drawer + +DAG Visualizations +================== + +.. autosummary:: + :toctree: ../stubs/ + + dag_drawer + +Pass Manager Visualizations +=========================== + +.. autosummary:: + :toctree: ../stubs/ + + pass_manager_drawer + + +Exceptions +========== + +.. autosummary:: + :toctree: ../stubs/ + + VisualizationError +""" + +import os import sys from qiskit.util import _has_connection from qiskit.visualization.counts_visualization import plot_histogram @@ -33,7 +110,8 @@ from .exceptions import VisualizationError from .matplotlib import HAS_MATPLOTLIB -if ('ipykernel' in sys.modules) and ('spyder' not in sys.modules): +if (('ipykernel' in sys.modules) and ('spyder' not in sys.modules)) \ + or os.getenv('QISKIT_DOCS') == 'TRUE': if _has_connection('qvisualization.mybluemix.net', 443): from qiskit.visualization.interactive import (iplot_bloch_multivector, iplot_state_city, diff --git a/qiskit/visualization/counts_visualization.py b/qiskit/visualization/counts_visualization.py index 2f11d5da74b6..fdcd13697419 100644 --- a/qiskit/visualization/counts_visualization.py +++ b/qiskit/visualization/counts_visualization.py @@ -82,6 +82,22 @@ def plot_histogram(data, figsize=(7, 5), color=None, number_to_keep=None, ImportError: Matplotlib not available. VisualizationError: When legend is provided and the length doesn't match the input data. + + Example: + .. jupyter-execute:: + + from qiskit import QuantumCircuit, BasicAer, execute + from qiskit.visualization import plot_histogram + %matplotlib inline + + qc = QuantumCircuit(2, 2) + qc.h(0) + qc.cx(0, 1) + qc.measure([0, 1], [0, 1]) + + backend = BasicAer.get_backend('qasm_simulator') + job = execute(qc, backend) + plot_histogram(job.result().get_counts()) """ if not HAS_MATPLOTLIB: raise ImportError('Must have Matplotlib installed.') diff --git a/requirements-dev.txt b/requirements-dev.txt index a9707c79d52c..7878c3c92bac 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -21,4 +21,5 @@ 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 +sphinx-automodapi +jupyter-sphinx \ No newline at end of file diff --git a/tox.ini b/tox.ini index 0b1a1007c945..687190d0bbaf 100644 --- a/tox.ini +++ b/tox.ini @@ -35,5 +35,7 @@ commands = [testenv:docs] deps = -r{toxinidir}/requirements-dev.txt + qiskit-aer + qiskit-ibmq-provider commands = sphinx-build -b html docs/ docs/_build/html {posargs}