Module level documentation for qiskit.visualization (Qiskit#3187)

* update visualization docs

* style

* add width change

* quanum -> quantum

* add coloring to function links

* add otehr visuals

* simplify even more

* more styling

* styling

* a bit softer link color

* add example

* add inline

* Add qiskit-aer and qiskit-ibmq-provider to docs job

Using jupyter-sphinx to build examples in the docs enables us to
actually run examples in the docs and get jupyter output. However, the
module fails by default if there is anything printed to stderr when
executing code. The base qiskit namespace will print a warning if ibmq
and aer are not found on a system (which is to provide cover for python
packaging issues). To avoid these warnings the simplest step is to
install both packages into the venv to avoid a warning. This commit does
just that.

.gitignore

@@ -140,3 +140,6 @@ src/qasm-simulator-cpp/test/qubit_vector_tests
 
 # Cython pass
 qiskit/transpiler/passes/**/cython/**/*.cpp
+
+docs/api/*
+docs/stubs/*

docs/_static/style.css

@@ -0,0 +1,12 @@
+.wy-nav-content {
+    max-width: 90% !important;
+}
+
+.wy-side-scroll {
+    background:#8c8c8c;
+}
+
+.pre
+{
+color:#BE8184;
+}

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

docs/apidocs/visualization.rst

@@ -0,0 +1,6 @@
+.. _qiskit-visualization:
+
+.. automodule:: qiskit.visualization
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

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',
+}
+

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,

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.')

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
+sphinx-automodapi
+jupyter-sphinx

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}