Add docs build jobs (#415)

.gitignore

@@ -28,3 +28,8 @@ contrib/standalone/version.hpp
 test/.asv
 
 .tox/
+
+docs/_build/
+docs/stubs/
+docs/api/
+

azure-pipelines.yml

@@ -7,39 +7,66 @@ trigger:
 - master
 - stable
 
-pool:
-  vmImage: 'vs2017-win2016'
-strategy:
-  matrix:
-    Python35:
-      python.version: '3.5'
-    Python36:
-      python.version: '3.6'
-    Python37:
-      python.version: '3.7'
-
-steps:
-  - powershell: Write-Host "##vso[task.prependpath]$env:CONDA\Scripts"
-    displayName: Add conda to PATH
-  - script: conda create --yes --quiet --name qiskit-aer-$(Build.BuildNumber)
-    displayName: Create Anaconda environment
-  - script: |
-      call activate qiskit-aer-$(Build.BuildNumber)
-      conda install --yes --quiet --name qiskit-aer-$(Build.BuildNumber) python=%PYTHON_VERSION% numpy
-    displayName: Install Anaconda packages
-  - bash: |
-      set -e
-      source activate qiskit-aer-$(Build.BuildNumber)
-      git clean -fdX
-      python -m pip install --disable-pip-version-check pip==18
-      pip install cython
-      pip install git+https://github.com/Qiskit/qiskit-terra.git
-      pip install --ignore-installed -r requirements-dev.txt
-      python setup.py bdist_wheel -- -G "Visual Studio 15 2017 Win64"
-    displayName: 'Install Dependencies and Build Aer'
-  - bash: |
-      set -e
-      source activate qiskit-aer-$(Build.BuildNumber)
-      pip install dist/qiskit_aer*.whl
-      python -m unittest discover -s test/terra -v
-    displayName: 'Install Aer and Run Tests'
+jobs:
+  - job: 'Docs'
+    pool: {vmImage: 'ubuntu-16.04'}
+    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 virtualenv
+         pip install -U tox
+         sudo apt-get update
+         sudo apt-get install -y build-essential libopenblas-dev
+       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: 'Windows'
+    pool: {vmImage: 'vs2017-win2016'}
+    strategy:
+      matrix:
+        Python35:
+          python.version: '3.5'
+        Python36:
+          python.version: '3.6'
+        Python37:
+          python.version: '3.7'
+    steps:
+      - powershell: Write-Host "##vso[task.prependpath]$env:CONDA\Scripts"
+        displayName: Add conda to PATH
+      - script: conda create --yes --quiet --name qiskit-aer-$(Build.BuildNumber)
+        displayName: Create Anaconda environment
+      - script: |
+          call activate qiskit-aer-$(Build.BuildNumber)
+          conda install --yes --quiet --name qiskit-aer-$(Build.BuildNumber) python=%PYTHON_VERSION% numpy
+        displayName: Install Anaconda packages
+      - bash: |
+          set -e
+          source activate qiskit-aer-$(Build.BuildNumber)
+          git clean -fdX
+          python -m pip install --disable-pip-version-check pip==18
+          pip install cython
+          pip install git+https://github.com/Qiskit/qiskit-terra.git
+          pip install --ignore-installed -r requirements-dev.txt
+          python setup.py bdist_wheel -- -G "Visual Studio 15 2017 Win64"
+        displayName: 'Install Dependencies and Build Aer'
+      - bash: |
+          set -e
+          source activate qiskit-aer-$(Build.BuildNumber)
+          pip install dist/qiskit_aer*.whl
+          python -m unittest discover -s test/terra -v
+        displayName: 'Install Aer and Run Tests'

docs/_static/style.css

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

docs/autosummary/base.rst

@@ -0,0 +1,10 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/autosummary/class.rst

@@ -0,0 +1,49 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+      :toctree: ../stubs/
+   {% for item in all_attributes %}
+      {%- if not item.startswith('_') %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. rubric:: Methods
+
+   .. autosummary::
+      :toctree: ../stubs/
+   {% for item in all_methods %}
+      {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% for item in inherited_members %}
+      {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+      {{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}

docs/autosummary/module.rst

@@ -0,0 +1,41 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

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,16 +58,35 @@ release = '0.12.0'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.mathjax',
     'sphinx.ext.napoleon',
+    'sphinx.ext.autodoc',
+    'sphinx_automodapi.automodapi',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.extlinks',
     'sphinx_tabs.tabs',
-    'sphinx_automodapi.automodapi',
-    'IPython.sphinxext.ipython_console_highlighting',
-    'IPython.sphinxext.ipython_directive'
+    'jupyter_sphinx.execute',
 ]
+html_static_path = ['_static']
+templates_path = ['_templates']
+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
@@ -88,7 +112,7 @@ language = None
 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
@@ -112,5 +136,14 @@ modindex_common_prefix = ['qiskit.']
 #
 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',
+}

requirements-dev.txt

@@ -9,4 +9,5 @@ pycodestyle
 Sphinx>=1.8.3
 sphinx-rtd-theme>=0.4.0
 sphinx-tabs>=1.1.11 
-sphinx-automodapi
+sphinx-automodapi
+jupyter-sphinx

tox.ini

@@ -25,3 +25,12 @@ deps =
 commands =
   pycodestyle --ignore=E402,W504 --max-line-length=100 qiskit/providers/aer
   pylint -j 2 -rn qiskit/providers/aer
+
+[testenv:docs]
+deps =
+  -r requirements-dev.txt
+  git+https://github.com/Qiskit/qiskit-terra.git
+commands =
+  python setup.py bdist_wheel -- -- -j4
+  pip install --find-links={toxinidir}/dist qiskit_aer
+  sphinx-build -b html docs/ docs/_build/html {posargs}