Do mild editing for grammar, consistency, and Markdown (#7246)

* Add missing Markdown code block language tags

* Do mild editing for grammar & consistency

In one document, the constructs in a list of cards were not parallel.
In other places, just fiddled with constructs that struck me as
awkward.

* Update _index.yaml

Apply fix from @pavoljuhas for lint error.

---------

Co-authored-by: Pavol Juhas <[email protected]>

Author: mhucka

docs/build/_index.yaml

@@ -34,7 +34,7 @@ landing_page:
     - cards
     items:
     - heading: Operators
-      description: Unitary operators, measurements and noise channels.
+      description: Unitary operators, measurements, and noise channels.
       path: /cirq/build/operators
     - heading: Observables and PauliStrings
       description: Build and measure observables from sums and products of Pauli operators.

docs/dev/development.md

@@ -17,7 +17,7 @@ cd Cirq
 
 The following command will set up large refactoring revisions to be ignored, when using git blame.
 
-```
+```bash
 git config blame.ignoreRevsFile .git-blame-ignore-revs
 ```
 
@@ -27,13 +27,13 @@ Note that if you are using PyCharm, you might have to use the command Restart &
 You can build the stable and pre-release Docker images with our `Dockerfile`.
 
 ```bash
-    docker build -t cirq --target cirq_stable .
-    docker run -it cirq python -c "import cirq_google; print(cirq_google.Sycamore23)"
+docker build -t cirq --target cirq_stable .
+docker run -it cirq python -c "import cirq_google; print(cirq_google.Sycamore23)"
 ```
 
 ```bash
-    docker build -t cirq_pre --target cirq_pre_release .
-    docker run -it cirq_pre python -c "import cirq_google; print(cirq_google.Sycamore23)"
+docker build -t cirq_pre --target cirq_pre_release .
+docker run -it cirq_pre python -c "import cirq_google; print(cirq_google.Sycamore23)"
 ```
 
 If you want to contribute changes to Cirq, you will instead want to fork the repository and submit pull requests from your fork.
@@ -152,7 +152,7 @@ See the previous section for instructions.
 
 If you want to pip install Cirq in an editable fashion, you'll have to install it per module, e.g.:
 
-```
+```bash
 pip install -e ./cirq-core -e ./cirq-google -e ./cirq-ionq -e ./cirq-aqt
 ```
 
@@ -273,7 +273,7 @@ For this pull request you may want to mark it as `[Testing]` so that it is not r
 Cirq uses [Google style doc strings](http://google.github.io/styleguide/pyguide.html#381-docstrings) with a Markdown flavor and support for LaTeX.
 Here is an example docstring:
 
-```
+```python
 def some_method(a: int, b: str) -> float:
     r"""One line summary of method.
 
@@ -330,7 +330,7 @@ Instead, in the directory `dev_tools/requirements`, create a separate `<job>.env
 
 You can call the following utility to unroll the content of a file:
 
-```
+```bash
 python dev_tools/requirements/reqs.py dev_tools/requirements/dev.env.txt
 ```
 

docs/dev/serialization.md

@@ -35,13 +35,13 @@ print(text)
 
 The JSON can also be written to a file:
 
-```
+```python
 cirq.to_json(obj, filepath)
 ```
 
 Or read back in from a file:
 
-```
+```python
 obj = cirq.read_json(filepath)
 ```
 

docs/experiments/_index.yaml

@@ -6,7 +6,7 @@ landing_page:
   rows:
   - heading: Experiments using quantum circuits
     description: This is a collection of algorithms and experiments written in and
-      using Cirq. A couple of them use only base Cirq, but the rest use additional
+      using Cirq. A few use only base Cirq; the rest use additional
       code stored in ReCirq, a GitHub repository for research code that uses and builds
       upon Cirq.
   - buttons:
@@ -15,7 +15,7 @@ landing_page:
     - label: ReCirq GitHub
       path: https://github.com/quantumlib/ReCirq
   - heading: Algorithms in base Cirq
-    description: Algorithms and experiments executable using only default Cirq code.
+    description: Algorithms and experiments that use only default Cirq code.
     options:
     - cards
     items:
@@ -24,20 +24,20 @@ landing_page:
         shown in quantum textbooks.
       path: /cirq/experiments/textbook_algorithms
     - heading: Shor's Algorithm
-      description: The famous integer factorization algorithm by Peter Shor.
+      description: An implementation of the famous integer factorization algorithm by Peter Shor.
       path: /cirq/experiments/shor
     - heading: Variational Quantum Eigensolver
-      description: Compute the ground state of a Hamiltonian using the variational
-        principle.
+      description: An example of computing the ground state of a Hamiltonian using the
+        variational principle.
       path: /cirq/experiments/variational_algorithm
     - heading: Quantum Walks
-      description: The quantum analog of a random walk algorithm.
+      description: An example of the quantum analog of a random walk algorithm.
       path: /cirq/experiments/quantum_walks
     - heading: Fourier Checking
-      description: Demonstrate the separation between quantum and classical computers.
+      description: A demonstration of the separation between quantum and classical computers.
       path: /cirq/experiments/fourier_checking
     - heading: Hidden Linear Function problem
-      description: Show quantum separation with a constant depth solution.
+      description: An example showing quantum separation with a constant-depth solution.
       path: /cirq/experiments/hidden_linear_function
 
   - heading: ReCirq Experiments

docs/google/calibration.md

@@ -20,7 +20,7 @@ A dropdown menu will let you choose the current characterization or historical
 metrics from a previous run.  Calibration metrics can also be retrieved
 programmatically using an engine instance or with a job.
 
-```
+```python
 import cirq_google as cg
 
 # Create an Engine object to use.
@@ -167,7 +167,7 @@ calculated by fitting Gaussian distributions to the signals prepared in the
 distributions.  Note that this is a component of both the p_00 and p_11 errors
 and is included within those metrics.
 
-### Isolated 1 qubit randomized benchmark error: 
+### Isolated 1 qubit randomized benchmark error:
 *   Metric key: single_qubit_rb_average_error_per_gate
 *   Metric key: single_qubit_rb_pauli_error_per_gate
 *   Metric key: single_qubit_rb_incoherent_error_per_gate
@@ -186,7 +186,7 @@ More information about randomized benchmarking can be found in section 6.3
 (page 120) of this
 [thesis](https://web.physics.ucsb.edu/~martinisgroup/theses/Chen2018.pdf).
 
-### T1 
+### T1
 *   Metric key: single_qubit_idle_t1_micros
 
 The T1 of a qubit represents the time constant of the exponential decay of a

docs/google/devices.md

@@ -37,7 +37,7 @@ If a moment contains only these "virtual" gates, it will disappear.
 
 For example, this circuit will execute the two gates in parallel:
 
-```
+```python
 cirq.Circuit(
   cirq.Moment(cirq.X(cirq.GridQubit(4,4)), cirq.X(cirq.GridQubit(4,5)))
 )
@@ -46,7 +46,7 @@ cirq.Circuit(
 This circuit will execute the two gates in serial:
 
 
-```
+```python
 cirq.Circuit(
   cirq.Moment(cirq.X(cirq.GridQubit(4,4))),
   cirq.Moment(cirq.X(cirq.GridQubit(4,5)))
@@ -56,7 +56,7 @@ cirq.Circuit(
 Lastly, this circuit will only execute one gate, since the first gate
 is virtual and its moment will disappear:
 
-```
+```python
 cirq.Circuit(
   cirq.Moment(cirq.Z(cirq.GridQubit(4,4))),
   cirq.Moment(cirq.X(cirq.GridQubit(4,5)))
@@ -88,7 +88,7 @@ following code will sweep qubit (4,8)'s pi amplitude from 0.0 to 1.0
 in 0.02 increments.
 
 
-```
+```python
 descriptor = cirq_google.study.DeviceParameter( ["q4_8", "piAmp"])
 sweep = cirq.Linspace("q4_8.piAmp", 0, 1, 51, metadata=descriptor)
 ```
@@ -153,7 +153,7 @@ to affect the frequency of the qubit.
 This can be done by applying a PhysicalZTag to the Z gate,
 such as in the following example:
 
-```
+```python
 cirq.Z(cirq.GridQubit(5, 5)).with_tags(cirq_google.PhysicalZTag())
 ```
 

docs/google/engine.md

@@ -23,7 +23,7 @@ gcloud client:
 
 From a colab, you can execute:
 
-```
+```python
 from google.colab import auth
 auth.authenticate_user(clear_output=False)
 ```
@@ -239,4 +239,3 @@ for p in programs:
    for j in p.list_jobs(execution_states=[enums.ExecutionStatus.State.FAILURE]):
      print(j.job_id, j.status())
 ```
-

docs/google/specification.md

@@ -99,7 +99,7 @@ verify a circuit.
 The following example illustrates retrieving the device specification live
 from the engine and then using it to validate a circuit.
 
-```
+```python
 import cirq
 import cirq_google as cg
 

docs/transform/_index.yaml

@@ -5,7 +5,7 @@ landing_page:
   nav: left
   rows:
   - heading: Transform a circuit
-    description: Programmatically transform a provided circuit into another one to
+    description: Programmatically transform one circuit into another one to
       implement any compilation or optimization process that changes a circuit.
     options:
     - cards