Refactored docs #983

coruscating · 2022-11-30T14:56:00Z

Refactoring existing docs into four new areas: tutorials, how-tos, experiment guides, and the API reference. With contributions from @chriseclectic, @wshanks, @jaleipekoglu, and @spencerking.

Main changes:

Added introduction tutorials
Added how-tos (this has a lot of room for future expansion)
Added cards linking to each documentation area on the index page
Organized experiment guides by type and with representative thumbnails
Moved detailed API docs such as Curve Analysis to tutorials
Consolidated previous calibrations guides into the new calibrations tutorial
Changed the See Also section in docstrings to render the rst directly instead of parsing modules
Closes sphinx-panels is unmaintained #1014 by replacing sphinx-panels with sphinx-design
Upgraded qiskit-sphinx-theme to >=1.10
Removed usage of qiskit-ibmq-provider in docs and linked to migration guide
Parallelized sphinx build run (CI docs build went from 13 minutes to 10:20)
Various fixes to remove all Sphinx build warnings and forces CI to fail if there's a warning (warnings might still exist on mac)
Cleaned up and removed unnecessary style and template files
Added commands tox -edocs-parallel for a parallel build and renamed no jupyter-execute command to tox -edocs-minimal

merav-aharoni

Overall it looks very good. I made a few small comments in some of the files. Here are a few more general comments:

Why was T2Ramsey removed? I think a few other tutorials were not transferred to the guides, and I don't know if it was intentional.
I suggest adding a section on ExperimentData, including Status.
I suggest adding a section on AnalysisResult.
The section on guides should have an introductory sentence (as do the How to and Tutorials.
In the How-Tos, you can remove the How to at the beginning of every section (because you have the top How to).
For the experiment guides, I know you simply transferred the tutorials to be guides. I think they should be reviewed. Two particular comments - for Randomized Benchmarking, add an example of setting the gate_error_rate; In T2Hahn the English should be improved.

docs/tutorials/learning.rst

docs/tutorials/visualization.rst

docs/tutorials/curve_analysis.rst

docs/tutorials/data_processor.rst

docs/howtos/local_service.rst

docs/howtos/newexperimentdata.rst

docs/tutorials/learning.rst

docs/tutorials/intro.rst

docs/tutorials/calibrations.rst

docs/tutorials/custom_experiment.rst

yaelbh · 2022-12-18T06:54:35Z

docs/tutorials/custom_experiment.rst

+The FineAmplitude Experiment
+============================
+
+The ``FineAmplitude`` calibration experiment repeats N times per gate with a pulse to amplify the under-/over-rotations in the gate to determine the optimal amplitude.


To my understanding FineAmplitude is a characterization experiment, while the calibration version is FineAmplitudeCal.

@coruscating Please note this comment

You're right, and I've updated the characterization experiment docstring so that it doesn't say calibration experiment anymore.

docs/tutorials/custom_experiment.rst

docs/tutorials/learning.rst

yaelbh · 2022-12-18T07:40:21Z

docs/tutorials/learning.rst

+There are two core types of composite experiments:
+
+* **Parallel experiments** run across qubits simultaneously. The circuits cannot overlap in 
+  qubits used.


run across qubits simultaneously

It sounds like the parallelization comes from some distributed algorithm. It's not clear that new circuits are constructed, that combine circuits of the sub-experiments.

The circuits cannot overlap in qubits used.

It sounds like circuits of each sub-experiment are not allowed to overlap between themselves.

I suggest not to mention batch experiments here. This allows to remove the itemization and provide a longer comprehensive paragraph explaining the doing of parallel experiments.

I've added more explanations and a figure, do you think it's clear enough now?

The figure is great. The added sentence is still not clear, sorry :-). It still sound like sub-experiment circuits must have internally different qubits, and (until the figure) it's not clear what parallelized circuits means.

docs/tutorials/learning.rst

coruscating · 2023-02-14T14:28:55Z

@yaelbh @wshanks This is ready for final review. It also closes #1014.

yaelbh · 2023-02-15T08:16:03Z

docs/tutorials/getting_started.rst

+    parallel_data = parallel_exp.run(backend, seed_simulator=101).block_for_results()
+
+Note that when options are set for a composite experiment, the child 
+experiments's options are also set recursively. Let's examine how the parallel 


I don't think it's always true. It depends on the option.

Good catch, updated

docs/tutorials/getting_started.rst

docs/tutorials/custom_experiment.rst

yaelbh · 2023-02-15T08:31:06Z

docs/tutorials/custom_experiment.rst

+  from numpy.random import default_rng, Generator
+  from qiskit import QuantumCircuit
+  from qiskit_experiments.framework import BaseExperiment
+  from qiskit.quantum_info import random_pauli_list


Consider arranging the imports, like pylint usually requests. Do we have pylint for the code snippets?

Fixed these. I guess we can run a linter on the generated jupyter notebooks, but I don't know if we want to add that to the CI.

docs/tutorials/custom_experiment.rst

yaelbh · 2023-02-15T09:21:13Z

docs/tutorials/custom_experiment.rst

+        options.seed = None
+        return options
+
+    def circuits(self):


There's a subtle point that has to be clearly explained (perhaps it's already explained and I missed it). Naturally as a new-by user I'd expect the circuits to act on the physical qubits. Users have to understand that the circuit qubits are 0,..., len(physical_qubits), and a mapping is carried out later, in the transpilation.

This is also related to the explanation about parallel experiment, that says that the circuits are required to have different qubits. The accurate thing to say is that the sub-experiment must have different physical qubits.

Good point, added.

yaelbh · 2023-02-15T09:35:37Z

docs/tutorials/custom_experiment.rst

+  expdata_noise = exp.run(noise_backend, shots=shots)
+  counts_noise = expdata_noise.analysis_results("counts").value
+
+  # Run noisy direct simulation of original circuit without randomization


What do you mean by "direct simulation"?

It means simulating the original circuit without going through the experiment. I reworded so it should be less confusing now.

yaelbh · 2023-02-15T09:38:53Z

docs/tutorials/custom_experiment.rst

+Now we'll use what we've learned so far to make a full custom experiment from
+the :class:`.BaseExperiment` template.
+
+A randomized measurement experiment


Please revise the code of the experiment and analysis classes, in addition to my comments. It doesn't have the form of an example code that helps learn how to write an experiment.

I've started to break up the code with explanations in-between in the newest commit. What do you mean by this doesn't have the form of an example code? Do you think a dummy template experiment with the attributes, something like

class CustomExperiment(BaseExperiment): def __init__(self, physical_qubits=None, dummy_option=None, backend=None): """Initialize the experiment.""" super().__init__(physical_qubits, analysis=CustomAnalysis(),backend=backend) self.set_experiment_options( dummy_option=dummy_option ) @classmethod def _default_experiment_options(cls) -> Options: options = super()._default_experiment_options() options.update_options( dummy_option=None, ) return options ...

would be helpful before introducing this experiment?

yaelbh · 2023-02-15T09:40:25Z

docs/tutorials/getting_started.rst

+
+Qiskit Experiments is built on top of Qiskit, so we recommend that you first install
+Qiskit following its :external+qiskit:doc:`installation guide <getting_started>`. 
+Qiskit Experiments supports the same platforms and Python versions (currently 3.7+) as 


Will we be aware about updating the Python version number here?

Yes, PRs to update Python version in the future should update this string. It would be nice to pull it automatically from setup.py but that will be work for another PR.

docs/tutorials/getting_started.rst

yaelbh · 2023-02-15T09:45:11Z

qiskit_experiments/library/characterization/t1.py

@@ -43,7 +42,8 @@ class T1(BaseExperiment):
        by fitting to an exponential curve.

    # section: analysis_ref
-        :py:class:`T1Analysis`
+        :py:class:`.T1Analysis`


What does the dot in the beginning mean?

There is a description here at the bottom of the section. Whether the dot is good here or not, I am not sure. T1Analysis is imported here so a search with the module name prepended should find it, but the real definition of T1Analysis is in a different module.

I have not tested, but using the . when there is a reference in scope might help suppress warnings like this one that I see in the output from the docs build:

/home/runner/work/qiskit-experiments/qiskit-experiments/docs/tutorials/getting_started.rst:100: WARNING: more than one target found for cross-reference 'run': qiskit_experiments.calibration_management.BaseCalibrationExperiment.run, qiskit_experiments.curve_analysis.BaseCurveAnalysis.run, qiskit_experiments.curve_analysis.BlochTrajectoryAnalysis.run

I added this particular dot on the off chance it fixed all the T1 warnings (it did not), but it's optional here. In general, if the object name is unique, using dot then the name is much shorter than writing out the full path. A common problem in our docs are broken cross references because the wrong path is used or people tried to reference an object in a different path without the dot, so I think it's good to get into the habit of writing it this way. One caveat with the dot is when there are multiple objects with the same name, as shown in @wshanks's example, where you should use something like :meth:`.BaseCurveAnalysis.run` to disambiguate instead if you're trying to reference the object that's not your local one.

wshanks · 2023-02-16T22:56:24Z

Could we try to eliminate as many of the warnings and errors from sphinx as we can here? I think the jupyter-execute warning might be out of our control. We should be able to deal with this one:

WARNING: [autosummary] failed to import qiskit_experiments.visualization.CurvePlotter.drawer.
Possible hints:
* ImportError: 
* AttributeError: type object 'CurvePlotter' has no attribute 'drawer'
* ModuleNotFoundError: No module named 'qiskit_experiments.visualization.CurvePlotter'
WARNING: [autosummary] failed to import qiskit_experiments.visualization.IQPlotter.drawer.
Possible hints:
* ModuleNotFoundError: No module named 'qiskit_experiments.visualization.IQPlotter'
* ImportError: 
* AttributeError: type object 'IQPlotter' has no attribute 'drawer'

Could we do something about all the occurrences of <rst_prolog>:2: ERROR: Content block expected for the "raw" directive; none found.?

The docs build okay with the warnings, but they are off-putting for people new to building the docs and can be misleading if someone adds documentation and thinks they might have been the cause of the warnings.

wshanks

Here are a couple initial comments.

docs/index.rst

coruscating · 2023-02-17T18:25:42Z

Could we try to eliminate as many of the warnings and errors from sphinx as we can here? I think the jupyter-execute warning might be out of our control. We should be able to deal with this one:

WARNING: [autosummary] failed to import qiskit_experiments.visualization.CurvePlotter.drawer.
Possible hints:
* ImportError: 
* AttributeError: type object 'CurvePlotter' has no attribute 'drawer'
* ModuleNotFoundError: No module named 'qiskit_experiments.visualization.CurvePlotter'
WARNING: [autosummary] failed to import qiskit_experiments.visualization.IQPlotter.drawer.
Possible hints:
* ModuleNotFoundError: No module named 'qiskit_experiments.visualization.IQPlotter'
* ImportError: 
* AttributeError: type object 'IQPlotter' has no attribute 'drawer'

@wshanks I've been looking into these errors but I'm still unsure what's causing them. I compared one of the experiment classes that has build errors (and actually doesn't build for me at all locally, though the CI build works) with one that doesn't, but I couldn't seen anything different.

Could we do something about all the occurrences of <rst_prolog>:2: ERROR: Content block expected for the "raw" directive; none found.?

These go away if rst_prolog is taken out of docs/conf.py, but then there's a lot of white space that inexplicably appears at the top of every page:

I'm sure this is a solvable problem since other docs don't have that gap but I'm not sure yet where the problem lies.

coruscating · 2023-02-27T07:54:19Z

@wshanks I've fixed the excess whitespace issue, but the build warnings seems to be a known mac-only local issue with no obvious fix: sphinx-doc/sphinx#10943

wshanks · 2023-03-04T04:14:29Z

One thing I noticed -- some of the tutorials / guides dump files into the top level of the repo:

jupyter_execute/                                              
PulseBackend*.csv

Could we get these files written to a temporary directory that gets cleaned up? Or at least a directory under docs/ that is in .gitignore?

Also updated the navigation to link to individual tutorials and updated the composite experiment figure to be more readable.

…iments into refactored-docs

updated logic so that the attribute section is only rendered if there are valid elements

Linux builds don't like to see class variables, and they're already documented via the docstring so we can just skip them

Because of issues on mac, `tox -edocs` doesn't have multiprocessing anymore. the `docs-parallel` env has been added for CI and Linux builders. `docsnorst` renamed to `docs-minimal`. The class template for methods has been updated like attributes so the header doesn't render unless there are valid members.

wshanks

Here are some review comments on the new content.

docs/tutorials/custom_experiment.rst

wshanks · 2023-03-13T20:12:47Z

docs/tutorials/custom_experiment.rst

+            meas_nc = len(self._measured_qubits)
+
+            # Classical bits of the circuit
+            circ_clbits = list(range(circ_nc))


Maybe somewhere you want to mention that the input circuit could mid-circuit measurements? Or maybe for the sake of the example it is cleaner to assume no extra measurements and the measurements added by the experiment are the only measurements?

I added a simple mid-circuit measurement circuit at the end to demonstrate this, though I don't run it. Maybe there's a more interesting example to actually run?

docs/howtos/job_splitting.rst

docs/howtos/new_experimentdata.rst

wshanks

Looks good to me!

### Summary This PR is essentially the documentation fixes from #1080 since the lint CI pipeline needs more work. ### Details and comments - The docs are no longer incompatible with the newest sphinx-autodoc-typehints so the version pin from #1017 has been removed. This closes #1018. - Updates curve analysis tutorial to the newest version (#983 had accidentally reverted to an older version) - Changes arxiv autolinks from pdfs to abstract page to be more user friendly - Renames the new ExperimentData how-to to rerunning analysis and adds additional info on using `add_data` - Moved functions from `curve_analysis/data_processing.py` to `utils.py` - Changes benchmarking experiments to verification experiments on the manual page to match the library API page - Added referenced classes and functions that weren't included in the docs - Various formatting fixes for passing Sphinx nitpick mode

merav-aharoni reviewed Dec 11, 2022

View reviewed changes

coruscating added this to the Release 0.5 milestone Dec 13, 2022

yaelbh reviewed Dec 15, 2022

View reviewed changes

docs/tutorials/intro.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/calibrations.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Dec 18, 2022

View reviewed changes

coruscating changed the title ~~[WIP] Refactored docs~~ Refactored docs Jan 18, 2023

wshanks mentioned this pull request Feb 8, 2023

Update characterization and calibration experiments to use physical_qubits #1037

Merged

yaelbh reviewed Feb 15, 2023

View reviewed changes

docs/tutorials/getting_started.rst Outdated Show resolved Hide resolved

yaelbh reviewed Feb 15, 2023

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Feb 15, 2023

View reviewed changes

docs/tutorials/custom_experiment.rst Outdated Show resolved Hide resolved

yaelbh reviewed Feb 15, 2023

View reviewed changes

wshanks reviewed Feb 16, 2023

View reviewed changes

docs/index.rst Show resolved Hide resolved

docs/index.rst Outdated Show resolved Hide resolved

added warning and test

17c4ab0

coruscating and others added 12 commits March 9, 2023 14:48

Merge branch 'main' into refactored-docs

3de94b2

Pin theme version to commit id

fe8b9a6

Also updated the navigation to link to individual tutorials and updated the composite experiment figure to be more readable.

Merge branch 'refactored-docs' of github.com:coruscating/qiskit-exper…

6d35140

…iments into refactored-docs

change experiment guide to manual

eea7382

update jinja template

34b938c

updated logic so that the attribute section is only rendered if there are valid elements

skipped members throwing warnings

49d3016

Linux builds don't like to see class variables, and they're already documented via the docstring so we can just skip them

fixed user manual section in docstrings

edb8ef8

Merge main, update theme, and format footnotes

c2292ac

fix merge conflicts

145ba35

fixed styling

77c0a9f

added docstring

2014a59

wshanks reviewed Mar 13, 2023

View reviewed changes

coruscating added 2 commits March 13, 2023 18:18

addressed review comments

e14dec1

minor edits

a0e2b40

wshanks approved these changes Mar 14, 2023

View reviewed changes

coruscating added this pull request to the merge queue Mar 14, 2023

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Mar 14, 2023

This was referenced Mar 14, 2023

The new visualization module could use a user guide and/or migration guide. #953

Closed

Document how to load an experiment without the cloud #919

Closed

coruscating added this pull request to the merge queue Mar 14, 2023

Merged via the queue into qiskit-community:main with commit 94531e6 Mar 14, 2023

This was referenced Mar 14, 2023

Table of contents not shown #587

Closed

Fix class attribute documentation generation #1078

Open

[WIP] Refactor tutorial for calibration experiments #499

Closed

Documentation fixes and formatting #1095

Merged

coruscating deleted the refactored-docs branch April 1, 2023 02:29

coruscating mentioned this pull request Feb 1, 2024

Add artifacts interface #1342

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactored docs #983

Refactored docs #983

coruscating commented Nov 30, 2022 •

edited

Loading

merav-aharoni left a comment

yaelbh Dec 18, 2022

yaelbh Feb 15, 2023

coruscating Feb 17, 2023

yaelbh Dec 18, 2022

coruscating Feb 14, 2023

yaelbh Feb 15, 2023

coruscating commented Feb 14, 2023

yaelbh Feb 15, 2023

coruscating Feb 27, 2023

yaelbh Feb 15, 2023

coruscating Feb 28, 2023

yaelbh Feb 15, 2023

coruscating Feb 28, 2023

yaelbh Feb 15, 2023

coruscating Feb 28, 2023 •

edited

Loading

yaelbh Feb 15, 2023

coruscating Feb 17, 2023

yaelbh Feb 15, 2023

coruscating Feb 28, 2023

yaelbh Feb 15, 2023

wshanks Feb 16, 2023

wshanks Feb 16, 2023

coruscating Feb 17, 2023 •

edited

Loading

wshanks commented Feb 16, 2023 •

edited

Loading

wshanks left a comment

coruscating commented Feb 17, 2023

coruscating commented Feb 27, 2023

wshanks commented Mar 4, 2023

wshanks left a comment

wshanks Mar 13, 2023

coruscating Mar 13, 2023

wshanks left a comment

Refactored docs #983

Refactored docs #983

Conversation

coruscating commented Nov 30, 2022 • edited Loading

merav-aharoni left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coruscating commented Feb 14, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coruscating Feb 28, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coruscating Feb 17, 2023 • edited Loading

Choose a reason for hiding this comment

wshanks commented Feb 16, 2023 • edited Loading

wshanks left a comment

Choose a reason for hiding this comment

coruscating commented Feb 17, 2023

coruscating commented Feb 27, 2023

wshanks commented Mar 4, 2023

wshanks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wshanks left a comment

Choose a reason for hiding this comment

coruscating commented Nov 30, 2022 •

edited

Loading

coruscating Feb 28, 2023 •

edited

Loading

coruscating Feb 17, 2023 •

edited

Loading

wshanks commented Feb 16, 2023 •

edited

Loading