Merge branch 'master' into releasenotes-fold

.github/CODEOWNERS

@@ -2,28 +2,28 @@
 # modify particular files in the repo. The PR can be merged when approved by at 
 # least one codeowner. However, all Qiskit team members can (and should!) review the PRs.
 
+# Global rule, unless specialized by a later one
+* @ajavadia @kdk @mtreinish @1ucian0
+
 # Individual folders on root directory
 /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
-circuit/              @ajavadia @kdk @ewinston @jaygambetta @1ucian0
-compiler/             @jaygambetta @ajavadia @kdk
-converters/           @mtreinish @1ucian0
+circuit/              @ajavadia @kdk @ewinston @1ucian0 @mtreinish
+extensions/           @ajavadia @kdk @ewinston @1ucian0 @mtreinish
 dagcircuit/           @ajavadia @kdk @1ucian0 @maddy-tod
-extensions/           @ajavadia @kdk @ewinston
-providers/            @diego-plan9 @mtreinish
+providers/            @ajavdia @mtreinish @diego-plan9
 basicaer/             @chriseclectic @ajavadia
 pulse/                @lcapelluto @taalexander @eggerdj @nkanazawa1989
-qobj/                 @diego-plan9 @jyu00 @taalexander
-quantum_info/         @chriseclectic @jaygambetta @levbishop @ajavadia
+quantum_info/         @chriseclectic @ajavadia
 qi/                   @chriseclectic @ajavadia
-result/               @diego-plan9 @jyu00 @taalexander @mtreinish
+result/               @diego-plan9 @jyu00 @taalexander @mtreinish @ajavadia
 schemas/              @diego-plan9 @dcmckayibm
-qiskit/tools/         @nonhermitian
 transpiler/           @ajavadia @kdk @1ucian0 @itoko @mtreinish
-validation/           @diego-plan9 @atilag
-visualization/        @nonhermitian @mtreinish @1ucian0 @maddy-tod
+assembler/            @ajavadia @kdk @diego-plan @taalexander @mtreinish
+qobj/                 @diego-plan9 @jyu00 @taalexander @kdk
+validation/           @ajavadia @diego-plan @taalexander @mtreinish
+visualization/        @nonhermitian @mtreinish @1ucian0 @maddy-tod @ajavadia

.gitignore

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

.pylintrc

@@ -172,7 +172,7 @@ attr-rgx=[a-z_][a-z0-9_]{2,30}$
 attr-name-hint=[a-z_][a-z0-9_]{2,30}$
 
 # Regular expression matching correct argument names
-argument-rgx=[a-z_][a-z0-9_]{2,30}$
+argument-rgx=[a-z_][a-z0-9_]{2,30}|ax$
 
 # Naming hint for argument names
 argument-name-hint=[a-z_][a-z0-9_]{2,30}$

.travis.yml

@@ -107,6 +107,7 @@ jobs:
         directories:
         - .hypothesis
       script:
+      - pip install -U pip
       - python setup.py build_ext --inplace
       - pip install "qiskit-aer"
       - make test_randomized

CONTRIBUTING.md

@@ -526,6 +526,125 @@ the following steps:
 The `stable/*` branches should only receive changes in the form of bug
 fixes.
 
+## Deprecation Policy
+
+End users of Qiskit need to know if a feature or an API they are using and rely
+on will still be supported by the software tomorrow. Users rely on existing
+features, knowing under which conditions the project can remove (or change in a
+backwards incompatible manner) a feature or API is important. To manage
+expectations the following policy is how API and feature deprecation and removal
+is handled by Qiskit:
+
+1. Features, APIs or configuration options are marked deprecated in the code.
+Appropriate `DeprecationWarning` class warnings will be sent to the user. The
+deprecated code will be frozen and receive only minimal maintenance (just so
+that it continues to work as-is).
+
+2. A migration path will be documented for current users of the feature. This
+will be outlined in the both the release notes adding the deprecation and the
+release notes removing the feature at the completion of the deprecation cycle.
+In addition, if feasible the warning message will also include the migration
+path. A migration path might be "stop using that feature", but in such cases
+it is necessary to first judge how widely used and/or important the feature
+is to end users and decided an obsolescence date based on that.
+
+3. An obsolescence date for the feature will be set. The feature must remain
+intact and working (although with the proper warning being emitted) in all
+releases pushed until after that obsolescence date. At the very minimum the
+feature (or API, or configuration option) should be marked as deprecated (and
+still be supported) for at least three months of linear time from the release
+date of the first release to include the deprecation warning. For example, if a
+feature were deprecated in the 0.9.0 release of terra, which was released on
+August 22, 2019, then that feature should still appear in all releases until at
+least November 22, 2019. Since releases do not occur at fixed time intervals
+this may mean that a deprecation warning may only occur in one release prior to
+removal.
+
+Note that this delay is a minimum. For significant features, it is recommend
+that the deprecated feature appears for at least double that time. Also, per
+the stable branch policy, deprecation removals can only occur during minor
+version releases, they are not appropriate for backporting.
+
+### Deprecation Warnings
+
+The proper way to raise a deprecation warning is to use the ``warn`` function
+from the [`warnings` module](https://docs.python.org/3/library/warnings.html)
+in the python standard library. The warning category class
+should be a ``DeprecationWarning``. An example would be:
+
+```python
+import warnings
+
+def foo(input):
+    warnings.warn('The qiskit.foo() function is deprecated as of 0.9.0, and '
+                  'will be removed no earlier than 3 months after that release '
+                  'date. You should use the qiskit.bar() function instead.',
+                  DeprecationWarning, stacklevel=2)
+```
+
+One thing to note here is the `stack_level` kwarg on the warn() call. This
+argument is used to specify which level in the call stack will be used as
+the line initiating the warning. Typically `stack_level` should be set to 2
+as this will show the line calling the context where the warning was raised.
+In the above example it would be the caller of `foo()`. If you did not set this,
+the warning would show that the warning was caused by the line in the foo()
+function, which is not helpful for users when trying to determine the origin
+of a deprecated call. This value may be adjust though depending on the call
+stack and where `warn()` gets called from. For example, if the warning is always
+raised by a private method that only has one caller `stack_level=3` might be
+appropriate.
+
+### Deprecation Release Notes
+
+You can refer to the Release Notes section for the process of creating a
+new release note. One thing to keep in mind for deprecation release notes
+though is that we need to clearly document a migration path in that release note.
+This should outline what the current deprecated behavior would look like and
+how users will need to update their code when that deprecated feature is
+removed. In addition it is also good to explain the reasoning behind why the
+change was being made. This provides context for users as to why they want
+to update their code using Qiskit. A simple example would be:
+
+```yaml
+
+deprecations:
+  - |
+    The function ``qiskit.foo()`` has been deprecated. An alternative function
+    ``qiskit.bar()`` can be used instead to provide the same functionality.
+    This alternative function provides the exact same functionality but with
+    better performance and more thorough validity checking.
+```
+
+In addition the `Changelog: Deprecation` label should be applied to any PRs
+adding deprecation warnings so that they are highlighted in the changelog for
+the release.
+
+#### Deprecation Removal Release Notes
+
+When an obsolecense date has passed and it's been determined safe to remove a
+deprecated feature from Qiskit we need to have an upgrade note in the release
+notes. We can copy the migration path from the deprecation release
+note but we should also indicate that the feature was deprecated and in which
+release. For example, building off the example in the previous section, if
+that deprecation occurred in the 0.9.0 release which occurred on August 22, 2019
+and the removal occurred in the **hypothetical** 0.11.0 release on December 2nd,
+2019 the release note would look like:
+
+```yaml
+upgrade:
+  - |
+    The previously deprecated function ``qiskit.foo()``, which was deprecated
+    in the 0.9.0 release, has been removed. The ``qiskit.bar()`` function
+    should be used instead. ``qiskit.bar()`` provides the exact same
+    functionality but with better performance and more thorough validity
+    checking.
+```
+
+Pull requests that remove a deprecated function will need to be tagged with the
+`Changelog: Removal` label so that they get highlighted in the changelog for
+the release.
+
+
 ## Stable Branch Policy
 
 The stable branch is intended to be a safe source of fixes for high

README.md

@@ -46,7 +46,7 @@ In this case, the output will be:
 {'00': 513, '11': 511}
 ```
 
-A script is available [here](examples/python/hello_quantum.py), where we also show how to
+A script is available [here](examples/python/ibmq/hello_quantum.py), where we also show how to
 run the same program on a real quantum computer via IBMQ.  
 
 ### Executing your code on a real quantum chip

azure-pipelines.yml

@@ -37,6 +37,8 @@ stages:
           condition: succeededOrFailed()
         - bash: |
             twine upload wheelhouse/*
+          env:
+            TWINE_PASSWORD: $(TWINE_PASSWORD)
     - job: 'sdist'
       pool: {vmImage: 'Ubuntu-16.04'}
       condition: startsWith(variables['Build.SourceBranch'], 'refs/tags')
@@ -54,6 +56,8 @@ stages:
           condition: succeededOrFailed()
         - bash: |
             twine upload dist/*
+          env:
+            TWINE_PASSWORD: $(TWINE_PASSWORD)
     - job: 'macos'
       condition: startsWith(variables['Build.SourceBranch'], 'refs/tags')
       pool: {vmImage: 'macOS-10.13'}
@@ -75,6 +79,8 @@ stages:
         condition: succeededOrFailed()
       - bash: |
           twine upload wheelhouse/*
+        env:
+          TWINE_PASSWORD: $(TWINE_PASSWORD)
     - job: 'Windows'
       pool: {vmImage: 'vs2017-win2016'}
       condition: startsWith(variables['Build.SourceBranch'], 'refs/tags')
@@ -103,6 +109,8 @@ stages:
           condition: succeededOrFailed()
         - bash: |
             twine upload wheelhouse\*
+          env:
+            TWINE_PASSWORD: $(TWINE_PASSWORD)
   - stage: 'Lint_and_Tests'
     condition: not(startsWith(variables['Build.SourceBranch'], 'refs/tags'))
     jobs:
@@ -161,8 +169,8 @@ stages:
       condition: not(startsWith(variables['Build.SourceBranch'], 'refs/tags'))
       strategy:
         matrix:
-          Python35:
-            python.version: '3.5'
+          Python37:
+            python.version: '3.7'
       steps:
         - task: UsePythonVersion@0
           inputs:

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/VERSION.txt

@@ -1 +1 @@
-0.10.0
+0.11.0