Update docstring options parser and add docs cron job

.github/workflows/cron-staging.yml

@@ -44,4 +44,35 @@ jobs:
         if: runner.os == 'macOS'
         env:
           TEST_TIMEOUT: 120
-          OMP_NUM_THREADS: 1
+          OMP_NUM_THREADS: 1
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Pip cache
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-docs-${{ hashFiles('setup.py','requirements.txt','requirements-extras.txt','requirements-dev.txt','constraints.txt') }}
+      - name: Install Deps
+        run: |
+          python -m pip install -U tox
+          sudo apt-get install -y pandoc graphviz
+      - name: Build Docs
+        run: tox -edocs-terra-main
+      - name: Compress Artifacts
+        run: |
+          mkdir artifacts
+          tar -Jcvf html_docs.tar.xz docs/_build/html
+          mv html_docs.tar.xz artifacts/.
+      - uses: actions/upload-artifact@v3
+        with:
+          name: html_docs
+          path: artifacts

docs/_ext/custom_styles/option_parser.py

@@ -26,7 +26,7 @@
 from sphinx.ext.napoleon import GoogleDocstring
 
 
-_parameter_doc_regex = re.compile(r'(.+?)\(\s*(.*[^\s]+)\s*\):(.*[^\s]+)')
+_parameter_doc_regex = re.compile(r"(.+?)\(\s*(.*[^\s]+)\s*\):(.*[^\s]+)")
 
 
 class QiskitExperimentsOptionsDocstring(GoogleDocstring):
@@ -201,8 +201,11 @@ def _value_repr(value: Any) -> str:
         return f"{{{dict_repr}}}"
     if value.__class__.__module__ == "builtins":
         return f":obj:`{value}`"
-    if value.__class__.__module__.startswith("qiskit"):
+    if value.__class__.__module__ and value.__class__.__module__.startswith("qiskit"):
         return f"Instance of :class:`.{value.__class__.__name__}`"
+    # for singleton gates that don't have directly accessible module names
+    if hasattr(value, "base_class") and value.base_class.__module__.startswith("qiskit"):
+        return f"Instance of :class:`.{value.base_class.__name__}`"
     if callable(value):
         return f"Callable :func:`{value.__name__}`"
     if isinstance(value, np.ndarray):

docs/manuals/characterization/tphi.rst

@@ -54,11 +54,11 @@ relaxation time estimate. We can see that the component experiments of the batch
 .. jupyter-execute::
 
     exp = Tphi(physical_qubits=(0,), delays_t1=delays_t1, delays_t2=delays_t2, num_echoes=1)
-    exp.component_experiment(0).circuits()[-1].draw("mpl")
+    exp.component_experiment(0).circuits()[-1].draw(output="mpl", style="iqp")
 
 .. jupyter-execute::
 
-    exp.component_experiment(1).circuits()[-1].draw("mpl")
+    exp.component_experiment(1).circuits()[-1].draw(output="mpl", style="iqp")
 
 Run the experiment and print results:
 
@@ -94,7 +94,7 @@ experiment:
                t2type="ramsey", 
                osc_freq=1e5)
 
-    exp.component_experiment(1).circuits()[-1].draw("mpl")
+    exp.component_experiment(1).circuits()[-1].draw(output="mpl", style="iqp")
 
 Run and display results:
 

docs/manuals/verification/randomized_benchmarking.rst

@@ -215,20 +215,20 @@ The default RB circuit output shows Clifford blocks:
     # Run an RB experiment on qubit 0
     exp = StandardRB(physical_qubits=(0,), lengths=[2], num_samples=1, seed=seed)
     c = exp.circuits()[0]
-    c.draw("mpl")
+    c.draw(output="mpl", style="iqp")
 
 You can decompose the circuit into underlying gates:
 
 .. jupyter-execute::
 
-    c.decompose().draw("mpl")
+    c.decompose().draw(output="mpl", style="iqp")
 
 And see the transpiled circuit using the basis gate set of the backend:
 
 .. jupyter-execute::
 
     from qiskit import transpile
-    transpile(c, backend, **vars(exp.transpile_options)).draw("mpl", idle_wires=False)
+    transpile(c, backend, **vars(exp.transpile_options)).draw(output="mpl", style="iqp", idle_wires=False)
 
 .. note::
     In 0.5.0, the default value of ``optimization_level`` in ``transpile_options`` changed

docs/tutorials/calibrations.rst

@@ -172,7 +172,7 @@ Instantiate the experiment and draw the first circuit in the sweep:
 .. jupyter-execute::
 
     circuit = spec.circuits()[0]
-    circuit.draw(output="mpl")
+    circuit.draw(output="mpl", style="iqp")
 
 We can also visualize the pulse schedule for the circuit:
 
@@ -225,7 +225,7 @@ with different amplitudes.
 
 .. jupyter-execute::
 
-    rabi.circuits()[0].draw("mpl")
+    rabi.circuits()[0].draw(output="mpl", style="iqp")
 
 After the experiment completes the value of the amplitudes in the calibrations 
 will automatically be updated. This behaviour can be controlled using the ``auto_update``
@@ -316,7 +316,7 @@ negative amplitude.
     from qiskit_experiments.library import RoughDragCal
     cal_drag = RoughDragCal([qubit], cals, backend=backend, betas=np.linspace(-20, 20, 25))
     cal_drag.set_experiment_options(reps=[3, 5, 7])
-    cal_drag.circuits()[5].draw(output='mpl')
+    cal_drag.circuits()[5].draw(output="mpl", style="iqp")
 
 .. jupyter-execute::
 
@@ -393,7 +393,7 @@ over/under rotations is the highest.
 
     overamp_exp = FineXAmplitude((qubit,), backend=backend)
     overamp_exp.set_transpile_options(inst_map=inst_map)
-    overamp_exp.circuits()[4].draw(output='mpl')
+    overamp_exp.circuits()[4].draw(output="mpl", style="iqp")
 
 .. jupyter-execute::
 
@@ -460,7 +460,7 @@ error which we want to correct.
     from qiskit_experiments.library import FineSXAmplitudeCal
 
     amp_cal = FineSXAmplitudeCal((qubit,), cals, backend=backend, schedule_name="sx")
-    amp_cal.circuits()[4].draw(output="mpl")
+    amp_cal.circuits()[4].draw(output="mpl", style="iqp")
 
 Let's run the calibration experiment:
 

docs/tutorials/custom_experiment.rst

@@ -573,7 +573,7 @@ Let's use a GHZ circuit as the input:
     for i in range(1, nq):
         qc.cx(i-1, i)
 
-    qc.draw("mpl")
+    qc.draw(output="mpl", style="iqp")
 
 Check that the experiment is appending a random Pauli and measurements as expected:
 
@@ -586,7 +586,7 @@ Check that the experiment is appending a random Pauli and measurements as expect
 
     # Run ideal randomized meas experiment
     exp = RandomizedMeasurement(qc, num_samples=num_samples)
-    exp.circuits()[0].draw("mpl")
+    exp.circuits()[0].draw(output="mpl", style="iqp")
 
 We now run the experiment with a GHZ circuit on an ideal backend, which produces nearly
 perfect symmetrical results between :math:`|0000\rangle` and :math:`|1111\rangle`:
@@ -640,4 +640,4 @@ unaffected by the added randomized measurements, which use its own classical reg
         qc.cx(i-1, i)
 
     exp = RandomizedMeasurement(qc, num_samples=num_samples)
-    exp.circuits()[0].draw("mpl")
+    exp.circuits()[0].draw(output="mpl", style="iqp")

docs/tutorials/getting_started.rst

@@ -101,11 +101,11 @@ first and last circuits for our :math:`T_1` experiment:
 .. jupyter-execute::
 
     print(delays)
-    exp.circuits()[0].draw(output='mpl')
+    exp.circuits()[0].draw(output="mpl", style="iqp")
 
 .. jupyter-execute::
 
-    exp.circuits()[-1].draw(output='mpl')
+    exp.circuits()[-1].draw(output="mpl", style="iqp")
 
 As expected, the delay block spans the full range of time values that we specified.
 
@@ -331,11 +331,11 @@ child experiments can be accessed via the
 
 .. jupyter-execute::
 
-    parallel_exp.component_experiment(0).circuits()[0].draw(output='mpl')
+    parallel_exp.component_experiment(0).circuits()[0].draw(output="mpl", style="iqp")
 
 .. jupyter-execute::
 
-    parallel_exp.component_experiment(1).circuits()[0].draw(output='mpl')
+    parallel_exp.component_experiment(1).circuits()[0].draw(output="mpl", style="iqp")
 
 Similarly, the child analyses can be accessed via :meth:`.CompositeAnalysis.component_analysis` or via
 the analysis of the child experiment class:
@@ -353,7 +353,7 @@ circuits are composed together and then reassigned virtual qubit indices:
 
 .. jupyter-execute::
 
-    parallel_exp.circuits()[0].draw(output='mpl')
+    parallel_exp.circuits()[0].draw(output="mpl", style="iqp")
 
 During experiment transpilation, a mapping is performed to place these circuits on the
 physical layout. We can see its effects by looking at the transpiled
@@ -363,7 +363,7 @@ and the :class:`.StandardRB` experiment's gates are on physical qubits 3 and 1.
 
 .. jupyter-execute::
 
-    parallel_exp._transpiled_circuits()[0].draw(output='mpl')
+    parallel_exp._transpiled_circuits()[0].draw(output="mpl", style="iqp")
 
 :class:`.ParallelExperiment` and :class:`.BatchExperiment` classes can also be nested
 arbitrarily to make complex composite experiments.

requirements-dev.txt

@@ -1,3 +1,4 @@
+qiskit-terra>=0.45.0
 black~=22.0
 stestr
 pylint~=3.0.2

requirements-extras.txt

@@ -1,5 +1,5 @@
 qiskit-ibm-provider>=0.6.1 # for submitting experiments to backends through the IBM provider
 cvxpy>=1.3.2 # for tomography
 scikit-learn # for discriminators
-qiskit-aer>=0.11.0
+qiskit-aer>=0.11.0,<=0.12.2 # temporary version pin until 0.13.1 release
 qiskit_dynamics>=0.4.0 # for the PulseBackend

tox.ini

@@ -101,6 +101,20 @@ setenv =
 commands =
   sphinx-build -T -W --keep-going -b html {posargs} docs/ docs/_build/html
 
+[testenv:docs-terra-main]
+usedevelop = True
+passenv =
+  EXPERIMENTS_DEV_DOCS
+  PROD_BUILD
+  RELEASE_STRING
+  VERSION_STRING
+deps =
+  git+https://github.com/Qiskit/qiskit-terra
+  -r{toxinidir}/requirements-dev.txt
+  -r{toxinidir}/requirements-extras.txt
+commands =
+  sphinx-build -j auto -T -W --keep-going -b html {posargs} docs/ docs/_build/html
+
 [testenv:docs-clean]
 skip_install = true
 deps =