Apply suggestions from code review

Co-authored-by: Joel Pasvolsky <[email protected]>

Author: thisac

docs/Makefile

@@ -16,7 +16,7 @@ OUTFOLDER    = demos/out
 ADD_DOWNLOAD_BUTTONS ="$\
 \$$a$\
 :download:\`Download Python source code \<$$(basename $$1 .rst).py\>\`\n\n$\
-:download:\`Download as Jupyter notebook \<$$(basename $$1 .rst).ipynb\>\`\n"
+:download:\`Download as Jupyter Notebook \<$$(basename $$1 .rst).ipynb\>\`\n"
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -33,7 +33,7 @@ demos:
 	cp -a $(DEMOFOLDER)/. $(OUTFOLDER)
 
 	find $(DEMOFOLDER) -name '*.py' -exec sh -c '$(JUPYTEXT) --to ipynb $$1 --output "$(OUTFOLDER)/$$(basename $$1 .py).ipynb"' sh {} \;
-	find $(OUTFOLDER) -name '*.ipynb' -exec $(NBCONVERT) {} --to rst --output-dir=$(OUTFOLDER) --execute \;
+	find $(OUTFOLDER) -name '*.ipynb' -exec $(NBCONVERT) {} --to rst --output-dir=$(OUTFOLDER) --execute --RegexRemovePreprocessor.patterns="^%" \;
 	find $(OUTFOLDER) -name '*.rst' -exec sh -c 'sed -i "1s/^/.. _$$(basename $$1 .rst):\n\n/" $$1' sh {} \;
 
 	find $(OUTFOLDER) -name '*.rst' -exec sh -c 'sed -i -e $(ADD_DOWNLOAD_BUTTONS) $$1' sh {} \;

docs/demos/demos/intro_demo.py

@@ -13,32 +13,39 @@
 # ---
 
 """
-# Beginner's guide to `dwave-gate`
+# Beginner's Guide to `dwave-gate`
 
-With `dwave-gate` you can easily contruct and simulate quantum circuits. This tutorial will guide
-you through how to use the `dwave-gate` library to inspect different quantum gates, construct
-circuits out of them, and then simulate them using our performant state-vector simulator.
+`dwave-gate` lets you easily construct and simulate quantum circuits. 
 
-We begin by importing the necessary modules.
+This tutorial guides you through using the `dwave-gate` library to inspect, 
+construct circuits from, and simulate quantum gates using a performant 
+state-vector simulator.
+## Circuits and Operations
+Begin by importing the necessary modules.
+
+*   `Circuit` objects contain the full quantum circuit, with all the operations, 
+    measurements, qubits and bits. 
+*   Operations, or gates, are objects that contain information related to a
+    particular operation, including its matrix representation, potential 
+    decompositions, and how to apply it to a circuit.
 """
 
 from dwave.gate.circuit import Circuit
 import dwave.gate.operations as ops
 
 ###############################################################################
-# The `Circuit` object contains the full quantum circuit, with all the operations, measurements,
-# qubits and bits. Operations, or gates, are objects that contain information related to that
-# specific operation, including its matrix representation, potential decompositions, and how to
-# apply it to a circuit. Via the `operations` module, here shortened to `ops`, a variety of quantum
-# gates can be accessed.
+# You can use the `operations` module (shortened above to `ops`) to access a 
+# variety of quantum gates; for example, a Pauli X operator.
 
 ops.X()
 
 ###############################################################################
-# As we can see, any operation can be instantiated without declaring which qubits it should be
-# applied to. We can also call the matrix property on either the gate class itself or on an instance
-# (i.e., an instantiated operation, which can contain additional parameters and/or qubit
-# information).
+# Notice above that an operation can be instantiated without declaring which qubits 
+# it should be applied to. 
+#
+# You can also call the matrix property on either the gate class itself or on an 
+# instance (i.e., an instantiated operation, which can contain additional 
+# parameters and qubit information).
 
 ops.X.matrix
 
@@ -50,36 +57,44 @@
 ops.RZ(4.2).matrix
 
 ###############################################################################
-# Operations are applied when either the class, or an instance of the class, is called within a
-# circuit's context. They can be applied to the circuit in several different ways, as detailed
-# below. Both qubits and parameters can be passed either as single values (if supported by the gate)
-# or as sequences. Note that different types of gates accept slightly different argument, although
-# the qubits can _always_ be passed as sequences via the keyword argument `qubits`.
-#
-# When instantiated within a circuit context, operations must always be applied to specific qubits
-# which in turn must be part of the circuits qubit register. The qubit register can be accessed via
-# the named tuple returned by the context manager as `q`, indexing into it to retrieve the
-# corresponding qubit.
+# ## Circuit Context
+# You apply operations by calling, within the context of a circuit, either a 
+# class or an instance of a class. 
+# 
+# You can apply operations to a circuit in several different ways, as demonstrated
+# below. You can pass both qubits and parameters as either single values (when 
+# supported by the gate) or sequences. Note that different types of gates accept 
+# slightly different arguments, although you can _always_ pass the qubits as 
+# sequences via the keyword argument `qubits`.
 #
-# Let's start by creating a circuit object with 2 qubits in its register, and apply a single X-gate
-# to the first qubit.
+# Always apply any operations you instantiate within a circuit context to 
+# specific qubits in the circuit's qubit register. You can access the qubit 
+# register via the named tuple returned by the context manager as `q`, indexing 
+# into it to retrieve the corresponding qubit.
+# ## Registers
+# This example starts by creating a circuit object with two qubits in its 
+# register and applying a single X gate to the first qubit.
 
 circuit = Circuit(2)
 
 with circuit.context as reg:
     ops.X(reg.q[0])
 
 ###############################################################################
-# We can access the qubit register via the `Circuit.qregisters` attribute, which currently should
-# contain a single qubit register with 2 qubits in it, but could contain any number of qubit
-# registers. If we'd want to, we could add another register with the `Circuit.add_qregister(n)`
-# method, where `n` would be the number of qubits in the new register, or add a qubit with
-# `Circuit.add_qubit()`, optinally passing a qubit object and/or a register to which to add it.
+# You can access the qubit register via the `Circuit.qregisters` attribute. 
+# 
+# In the current example, this attribute contains a single qubit register with 
+# two qubits; it could contain any number of qubit registers. You can
 #
-# The registers tuple can also be unwrapped directly into a qubit register `q` (and a classical
-# register `c`, but we'll get into that later).
+# * add another register with the `Circuit.add_qregister(n)` method, where `n` 
+#   is the number of qubits in the new register 
+# * add a qubit with `Circuit.add_qubit()`, optionally passing a qubit object 
+#   and/or a register to which to add it.
 #
-# Below follows a few examples for how to apply different gates to the circuit.
+# You can also unwrap the registers tuple into a qubit register `q` (and a classical
+# register `c`).
+#
+# ## Example: Applying Various gates to a Circuit
 
 
 circuit = Circuit(3)
@@ -109,24 +124,23 @@
     ops.Toffoli(q)
 
 ###############################################################################
-# Printing the above circuit gives us some general information about the circuit: the type of
-# circuit, the number of qubits/bits and the number of operations.
+# You can print a circuit to see general information about it: type of circuit, 
+# number of qubits/bits, and number of operations.
 
 print(circuit)
 
 ###############################################################################
-# We can also access the operations in the circuit via the `Circuit.circuit` attribute. This will
-# return a list of all operations which we can iterate over and print in the console.
+# You can also access operations in a circuit using the `Circuit.circuit` 
+# attribute. The code below iterates over the returned list of all operations.
 
 
 for op in circuit.circuit:
     print(op)
 
 ###############################################################################
-# Note that e.g., CNOT and CX apply the exact same gate. CNOT is only an alias for CX (so they both
-# are labelled as CX in the circuit). There are also other aliases which you can spot either in the
-# source code for the operations module or read more about in the documentation.
-#
+# Note that the CNOT alias for the controlled NOT gate is labelled CX in the 
+# circuit. You can find all operation aliases in the source code and documentation 
+# for the operations module. 
 
 ###############################################################################
 # ## Simulating a circuit

docs/demos/index.rst

@@ -1,4 +1,4 @@
-Demos and examples
+Demos and Examples
 ==================
 
 ``dwave-gate`` demonstrations and examples.
@@ -7,7 +7,7 @@ Demos and examples
 Tutorials
 ---------
 
-.. card:: Beginner's guide to ``dwave-gate``
+.. card:: Beginner's Guide to ``dwave-gate``
     :link: intro_demo
     :link-type: ref
 

docs/requirements.txt

@@ -2,5 +2,9 @@ docutils==0.17.1
 sphinx==5.3.0
 sphinx-rtd-theme==1.1.1
 sphinx_autodoc_typehints==1.19.5
+sphinx-design==0.4.1
+ipykernel==6.23.1
+matplotlib==3.71
 nbconvert==7.4.0
-jupytext==1.14.5
+jupytext==1.14.5
+reno[sphinx]==3.5.0