Qiskit · kt474 · Mar 7, 2023 · Mar 6, 2023 · Mar 6, 2023 · Mar 6, 2023
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -55,8 +55,16 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -U tox
+          pip install nbqa docutils
           sudo apt install -y graphviz pandoc
           pip install -e .
+
+          wget https://github.com/errata-ai/vale/releases/download/v2.23.0/vale_2.23.0_Linux_64-bit.tar.gz
+          mkdir $HOME/bin && tar -xf vale_2.23.0_Linux_64-bit.tar.gz -C $HOME/bin
+          echo "$HOME/bin" >> $GITHUB_PATH
+      - name: Lint documentation
+        run: |
+          make docs-test
       - name: Build documentation
         run: tox -edocs
       - name: Upload documentation
@@ -144,4 +152,4 @@ jobs:
         uses: coverallsapp/[email protected]
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          parallel-finished: true
+          parallel-finished: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -270,6 +270,19 @@ out$> make style
 out$> make mypy
 ```
 
+If you edit any documentation, refer to [IBM Quantum's writing style
+guide](https://github.com/IBM/ibm-quantum-style-guide). You can use
+[Vale](https://vale.sh) to automatically check some of these rules for you.
+With Vale installed, run the following command
+
+```sh
+make docs-test
+```
+
+This test also runs on CI and will fail if Vale encounters any spelling
+mistakes. To add a word to the dictionary, add it to
+`test/docs/dictionary.txt`.
+
 ### Development Cycle
 
 The development cycle for qiskit-ibm  is all handled in the open using

diff --git a/Makefile b/Makefile
@@ -32,6 +32,9 @@ integration-test:
 e2e-test:
 	python -m unittest discover --verbose --top-level-directory . --start-directory test/e2e
 
+docs-test:
+	./test/docs/vale.sh
+
 unit-test-coverage:
 	coverage run -m unittest discover --verbose --top-level-directory . --start-directory test/unit
 	coverage lcov

diff --git a/docs/.vale.ini b/docs/.vale.ini
@@ -0,0 +1,12 @@
+StylesPath = ../test/docs
+MinAlertLevel = suggestion
+
+[[!_]**.{md,rst}]
+BasedOnStyles = IBMQuantum
+
+[apidocs/ibm-runtime.rst]
+IBMQuantum.Headings = NO
+
+# skip './stubs'
+[stubs/**]
+BasedOnStyles = ''
diff --git a/docs/apidocs/ibm-runtime.rst b/docs/apidocs/ibm-runtime.rst
@@ -1,5 +1,7 @@
+.. vale off
+
 *****************************************
-qiskit-ibm-runtime API Reference
+qiskit-ibm-runtime API reference
 *****************************************
 
 .. toctree::

diff --git a/docs/cloud/architecture-workload-isolation.rst b/docs/cloud/architecture-workload-isolation.rst
@@ -5,7 +5,7 @@ Learning about Qiskit Runtime architecture and workload isolation
 Qiskit Runtime jobs run in individual containers in an internal Kubernetes cluster to isolate jobs from any other activities of other users. Jobs are not shared or visible between service instances. However, all users that can access a service instance can see that instance’s jobs, or submit jobs the account owner might be charged for.
 
 
-Restricting Access to service instances
+Restricting access to service instances
 ---------------------------------------
 
 With Qiskit Runtime, you can create service instances that are IAM-managed resources. Accordingly, IAM-based access control can be used for these service instances.

diff --git a/docs/cloud/cloud-provider-org.rst b/docs/cloud/cloud-provider-org.rst
@@ -1,7 +1,7 @@
 Manage users
 ======================
 
-You can manage IBM Cloud users or ID provider users.  Follow the instructions in the relevant section, depending on your setup. 
+You can manage IBM Cloud users or ID provider (IDP) users.  Follow the instructions in the relevant section, depending on your setup. 
 
 * :ref:`cloud-users`
 * :ref:`provider-cloud`
@@ -42,7 +42,7 @@ Optional: Modify users’ project assignments
 
 2. Add access groups with **Assign group** or remove the user from an access group by clicking the three dot menu and choosing **Remove user**.
 
-User Flow
+User flow
 ~~~~~~~~~~~~~
 
 1. After they accept an invitation, users can log in through the `IBM Cloud portal <https://cloud.ibm.com/>`__.
@@ -135,7 +135,7 @@ Integrate the App ID instance as the ID provider for the administrator’s accou
 
 4. The default IdP URL is shown. Share this URL with users when they need to log in.
 
-Add Users
+Add users
 ~~~~~~~~~~
 
 When you use App ID as ID provider with the Cloud directory, you can create users in the IBM Cloud user interface.
@@ -314,7 +314,7 @@ User flow
    .. note::
       The administrator can always go to `Manage → Access (IAM) → Identity providers <https://cloud.ibm.com/iam/identity-providers>`__ to look up the ID provider URL.
 
-2. To work with Qiskit Runtime serive instances, users must create an API key by going to `Manage → Access (IAM) → API keys <https://cloud.ibm.com/iam/apikeys>`__.
+2. To work with Qiskit Runtime service instances, users must create an API key by going to `Manage → Access (IAM) → API keys <https://cloud.ibm.com/iam/apikeys>`__.
 
 3. For further information, users can review `Getting started, Step 2 <quickstart#install-packages>`__.
 

diff --git a/docs/cloud/cost.rst b/docs/cloud/cost.rst
@@ -13,7 +13,7 @@ Additionally, the system limit on the job execution time is 3 hours for a job th
 How to limit your cost
 ***********************
 
-The time your job takes (and therefore, its cost) depends on how many iterations you make in a session and how many shots are run in each iteration. Thus, you can manage your cost by running only as many iterations and shots as you need.
+The time your job takes (and therefore, its cost) depends on how many iterations you make in a session and how many shots are run in each iteration. Therefore, you can manage your cost by running only as many iterations and shots as you need.
 
 Additionally, an instance administrator can limit how much is spent. To set cost limits, navigate to the `IBM Cloud Instances page <https://cloud.ibm.com/quantum/instances>`__, then click the instance and set the **Cost limit**. The cost limit refers to the total cost of all jobs run with this instance since it was created, and it will always be greater than or equal to the Total cost. After the instance reaches the specified number of total seconds, no further jobs can be run and no more cost is incurred.
 
@@ -71,7 +71,7 @@ Set up spending notifications
 You can set up spending notifications to get notified when your account or a particular service reaches a specific spending threshold that you set. For information, see the `IBM Cloud account Type description <https://cloud.ibm.com/docs/account?topic=account-accounts>`__. IBM Cloud spending notifications must be used with other methods of cost management for several reasons:
 
 - The notifications trigger only *after* cost surpasses the specified limit.
-- Cost is submitted to the billing system hourly. Thus, a long delay might occur between the job submission and the spending notification being sent.
+- Cost is submitted to the billing system hourly. Therefore, a long delay might occur between the job submission and the spending notification being sent.
 - The billing system can take multiple days to get information to the invoicing system, which might cause further delay in notifications. For more information about how the IBM Cloud billing system works, see `Setting spending notifications <https://cloud.ibm.com/docs/billing-usage?topic=billing-usage-spending>`__.
 
 Next steps

diff --git a/docs/cloud/plans.rst b/docs/cloud/plans.rst
@@ -11,27 +11,27 @@ Lite plan
 
 A free plan that gives you access to quantum simulators to help you get started with Qiskit Runtime. It does not include access to IBM Quantum systems. The following simulators are included in this plan:
 
--  **ibmq_qasm_simulator**: A general-purpose simulator for simulating quantum circuits both ideally and subject to noise modeling. The simulation method is automatically selected based on the input circuits and parameters.
+-  ``ibmq_qasm_simulator``: A general-purpose simulator for simulating quantum circuits both ideally and subject to noise modeling. The simulation method is automatically selected based on the input circuits and parameters.
 
    -  **Type**: General, context-aware
    -  **Simulatable Qubits**: 32
 
--  **simulator_statevector**: Simulates a quantum circuit by computing the wave function of the qubit’s state vector as gates and instructions are applied. Supports general noise modeling.
+-  ``simulator_statevector``: Simulates a quantum circuit by computing the wave function of the qubit’s state vector as gates and instructions are applied. Supports general noise modeling.
 
    -  **Type**: Schrödinger wave function
    -  **Simulated Qubits**: 32
 
--  **simulator_mps**: A tensor-network simulator that uses a Matrix Product State (MPS) representation for the state that is often more efficient for states with weak entanglement.
+-  ``simulator_mps``: A tensor-network simulator that uses a Matrix Product State (MPS) representation for the state that is often more efficient for states with weak entanglement.
 
    -  **Type**: Matrix Product State
    -  **Simulated Qubits**: 100
 
--  **simulator_stabilizer**: An efficient simulator of Clifford circuits. Can simulate noisy evolution if the noise operators are also Clifford gates.
+-  ``simulator_stabilizer``: An efficient simulator of Clifford circuits. Can simulate noisy evolution if the noise operators are also Clifford gates.
 
    -  **Type**: Clifford
    -  **Simulated Qubits**: 5000
 
--  **simulator_extended_stabilizer**: Approximates the action of a quantum circuit by using a ranked-stabilizer decomposition. The number of non-Clifford gates determines the number of stabilizer terms.
+-  ``simulator_extended_stabilizer``: Approximates the action of a quantum circuit by using a ranked-stabilizer decomposition. The number of non-Clifford gates determines the number of stabilizer terms.
 
    -  **Type**: Extended Clifford (for example, Clifford+T)
    -  **Simulated Qubits**: 63

diff --git a/docs/cloud/quickstart-org.rst b/docs/cloud/quickstart-org.rst
@@ -10,7 +10,7 @@ Overview
 
    IBM Cloud provides various ways to implement these mechanisms described in this tutorial. There are several ways to achieve these objectives. Additionally, most of the steps in this tutorial are generic to IBM Cloud and not specific to Qiskit Runtime, except the custom role details.
 
-Involved Personas
+Involved personas
 ~~~~~~~~~~~~~~~~~
 
 The are several main personas that are mentioned in this tutorial:

diff --git a/docs/cloud/quickstart.rst b/docs/cloud/quickstart.rst
@@ -20,7 +20,7 @@ If you already created a Qiskit Runtime service instance or were invited to one
 1. From the `Qiskit Runtime Provisioning page <https://cloud.ibm.com/catalog/services/quantum-computing>`__, choose the appropriate service plan, depending on what you need access to. For more information about these plans, see the `Qiskit Runtime plans <plans.html>`__ topic.
 
       - **Lite**: Free simulators-only plan to help you get started with Qiskit Runtime. Learn to use Qiskit Runtime by following our examples and tutorials for one of the pre-built programs available for running circuits efficiently.
-      - **Standard**: A pay-as-you-go model for accessing IBM Quantum systems and simulators. Build your own programs and leverage all the benefits of Qiskit Runtime by running on real quantum hardware.
+      - **Standard**: A pay-as-you-go model for accessing IBM Quantum systems and simulators. Build your own programs and use all the benefits of Qiskit Runtime by running on real quantum hardware.
 
       Because this is not a free plan, it is important to understand how to best manage your costs. See `Manage the cost <cost.html>`__ for tips to limit your cost, how to set up spending notifications, and more.
 

diff --git a/docs/cloud/setup-terraform.rst b/docs/cloud/setup-terraform.rst
@@ -1,12 +1,12 @@
 Set up Terraform for Qiskit Runtime
 ===================================
 
-If you use Terraform to manage your infrastructure, the `IBM Cloud provider for Terraform <https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started>`__ supports provisioning Qiskit Runtime service instances. The generic "ibm_resource_instance" resource is used for that. The following parameters have to be specified:
+If you use Terraform to manage your infrastructure, the `IBM Cloud provider for Terraform <https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started>`__ supports provisioning Qiskit Runtime service instances. The generic ``ibm_resource_instance`` resource is used for that. The following parameters have to be specified:
 
 Provisioning with Terraform
 ---------------------------
 
-If you use Terraform to manage your infrastructure, the `IBM Cloud provider for Terraform <https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started>`__ supports provisioning Qiskit Runtime service instances. The generic "ibm_resource_instance" resource is used for that. The following parameters have to be specified:
+If you use Terraform to manage your infrastructure, the `IBM Cloud provider for Terraform <https://cloud.ibm.com/docs/ibm-cloud-provider-for-terraform?topic=ibm-cloud-provider-for-terraform-getting-started>`__ supports provisioning Qiskit Runtime service instances. The generic ``ibm_resource_instance`` resource is used for that. The following parameters have to be specified:
 
 -  ``name`` – The name of your service instance.
 -  ``service`` – Specify ``quantum-computing`` to provision Qiskit Runtime instances.
@@ -18,7 +18,7 @@ Optional parameters include:
 -  ``resource_group_id`` – Creates the service instance in the specified resource group.
 -  ``tags`` – Add tags to the resource.
 
-Example: Creating a Service Instance of Qiskit Runtime
+Example: Creating a service instance of Qiskit Runtime
 ------------------------------------------------------
 
 After the job completes, you can view the results.

diff --git a/docs/compare.rst b/docs/compare.rst
@@ -24,7 +24,7 @@ Qiskit Runtime offers advantages in workload performance. Variational
 algorithms can run on classical compute resources that are colocated
 with the QPUs through the Estimator primitive program. This allows users
 to run iterative algorithm circuits back to back. In addition, sessions
-can drive a sequence of jobs without having to requeue each job,
+can drive a sequence of jobs without having to re-queue each job,
 avoiding latencies of queue wait times after the session is actively
 running. As a result, Qiskit Runtime is much more efficient than its
 predecessors.

diff --git a/docs/faqs.rst b/docs/faqs.rst
@@ -1,7 +1,7 @@
 .. _faqs:
 
 #########################################
-Frequently Asked Questions
+Frequently asked questions
 #########################################
 
 .. toctree::

diff --git a/docs/faqs/max_execution_time.rst b/docs/faqs/max_execution_time.rst
@@ -8,7 +8,7 @@ To ensure fairness, there is a maximum execution time for each Qiskit Runtime jo
 a job exceeds this time limit, it is forcibly cancelled. This is represented in the job
 status as `Cancelled - Ran too long`. The maximum execution time is the
 smaller of 1) the system limit and 2) the ``max_execution_time`` defined by the program.
-The system limit is defined below:
+The system limit is defined as follows:
 
 Qiskit Runtime on IBM Cloud
 ---------------------------
@@ -34,7 +34,7 @@ The system limit on the job execution time is
 Note that a *premium user* here means a user who has access to backends in providers other than ibm-q/open/main.
 
 
-Other Limitations
+Other limitations
 -----------------
 
 - Programs cannot exceed 750KB in size.

diff --git a/docs/faqs/open_source_vs_ibm_cloud_primitives.rst b/docs/faqs/open_source_vs_ibm_cloud_primitives.rst
@@ -1,8 +1,8 @@
 .. _faqs/open_source_vs_ibm_cloud_primitives:
 
-=================================================================================================
-What is the difference between the open source primitives and primitives available via IBM Cloud?
-=================================================================================================
+=====================================================================================================
+What is the difference between the open source primitives and primitives available through IBM Cloud?
+=====================================================================================================
 
 The open source primitive contains the base classes (to define interfaces) and a reference implementation.
 The Qiskit Runtime primitive is planned to provide more sophisticated implementation (such as with error

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -6,7 +6,7 @@ Install Qiskit packages
 ========================
 
 Install these packages. They let you create circuits and work with primitive programs
-via Qiskit Runtime.
+through Qiskit Runtime.
 
 .. code-block:: bash
 
@@ -64,7 +64,7 @@ Run the Hello World program to ensure that your environment is set up properly:
     print(result)
 
 
-Getting started with Primitives
+Getting started with primitives
 =================================
 
 .. nbgallery::

diff --git a/docs/how_to/account-management.rst b/docs/how_to/account-management.rst
@@ -54,7 +54,7 @@ Alternatively, if you specified a name for your account when saving it, you can
 
   service = QiskitRuntimeService(name="prod")
 
-If you want to use your credentials for just the session instead of saving it, you can pass the credentials in when initializing the ``QiskitRuntimeService`` instance:
+If you want to use your credentials for just the session rather than saving it, you can pass the credentials in when initializing the ``QiskitRuntimeService`` instance:
 
 .. code-block:: python
 

diff --git a/docs/how_to/backends.rst b/docs/how_to/backends.rst
@@ -1,24 +1,24 @@
 Run on quantum backends
 =================================
 
-A **backend** represents either a simulator or a real quantum computer and are responsible for running quantum circuits and/or pulse schedules and returning results.
+A **backend** represents either a simulator or a real quantum computer and are responsible for running quantum circuits, running pulse schedules, and returning results.
 
 In qiskit-ibm-runtime, a backend is represented by an instance of the ``IBMBackend`` class. Attributes of this class provides information about this backend. For example:
 
-* name: Name of the backend.
-* instructions: A list of instructions the backend supports.
-* operation_names: A list of instruction names the backend supported.
-* num_qubits: The number of qubits the backend has.
-* coupling_map: Coupling map of the backend.
-* dt: System time resolution of input signals.
-* dtm: System time resolution of output signals.
+* ``name``: Name of the backend.
+* ``instructions``: A list of instructions the backend supports.
+* ``operation_names``: A list of instruction names the backend supported.
+* ``num_qubits``: The number of qubits the backend has.
+* ``coupling_map``: Coupling map of the backend.
+* ``dt``: System time resolution of input signals.
+* ``dtm``: System time resolution of output signals.
 
 Refer to the `API reference <https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.IBMBackend.html#qiskit_ibm_runtime.IBMBackend>`__ for a complete list of attributes and methods.
 
 Initialize the service
 ------------------------
 
-Before calling ``IBMBackend``, inialize the service:
+Before calling ``IBMBackend``, initialize the service:
 
 .. code-block:: python
 
@@ -110,8 +110,11 @@ As mentioned previously, the ``IBMBackend`` class attributes provide information
   backend.simulator #returns True or False, depending on whether it is a simulator
   backend.num_qubits #returns the number of qubits the backend has
 
+.. vale IBMQuantum.Spelling = NO
+
 See the `IBMBackend class documentation <https://qiskit.org/documentation/partners/qiskit_ibm_runtime/stubs/qiskit_ibm_runtime.IBMBackend.html#qiskit_ibm_runtime.IBMBackend>`__ for the full list of backend attributes.  
 
+.. vale IBMQuantum.Spelling = YES
 
 Find backend information from other channels
 --------------------------------------------------