From 49de5691b1b62db605d94aedce9c746d053a6357 Mon Sep 17 00:00:00 2001
From: Abe Coull <85974725+math411@users.noreply.github.com>
Date: Fri, 26 May 2023 11:10:36 -0700
Subject: [PATCH] docs: add a linter to check proper rst formatting and fix up
 incorrect docs (#111)

Co-authored-by: Abe Coull <accoull@amazon.com>
---
 setup.cfg                                     |  7 +++++++
 setup.py                                      |  1 +
 .../quantum_circuit_born_machine/qcbm.py      | 19 ++++++++++---------
 .../experimental/algorithms/simons/simons.py  |  4 ++--
 tox.ini                                       |  2 +-
 5 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/setup.cfg b/setup.cfg
index 88d3d1be..fa13221f 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -21,6 +21,9 @@ ignore =
     E231,
     # not pep8, black adds line break before binary operator
     W503,
+    # Google Python style is not RST until after processed by Napoleon
+    # See https://github.com/peterjc/flake8-rst-docstrings/issues/17
+    RST201,RST203,RST301,
 max_line_length = 100
 max-complexity = 10
 exclude =
@@ -30,3 +33,7 @@ exclude =
     bin
     build
     venv
+
+rst-roles =
+    # Python programming language:
+    py:func,py:mod,mod
diff --git a/setup.py b/setup.py
index d6775ef8..d626147a 100644
--- a/setup.py
+++ b/setup.py
@@ -36,6 +36,7 @@
         "test": [
             "black>=22.3.0",
             "flake8<=5.0.4",
+            "flake8-rst-docstrings",
             "isort",
             "pytest",
             "pytest-cov",
diff --git a/src/braket/experimental/algorithms/quantum_circuit_born_machine/qcbm.py b/src/braket/experimental/algorithms/quantum_circuit_born_machine/qcbm.py
index ecb01100..2255a3e7 100644
--- a/src/braket/experimental/algorithms/quantum_circuit_born_machine/qcbm.py
+++ b/src/braket/experimental/algorithms/quantum_circuit_born_machine/qcbm.py
@@ -23,13 +23,14 @@ class QCBM:
     """Quantum circuit Born machine.
 
     Example: n_layers = 1, n_qubits = 2
-    T  : |    0    |    1    |    2    |3|4|Result Types|
+    ::
+        T  : |    0    |    1    |    2    |3|4|Result Types|
 
-    q0 : -Rx(0.667)-Rz(0.783)-Rx(0.257)-C-X-Probability--
+        q0 : -Rx(0.667)-Rz(0.783)-Rx(0.257)-C-X-Probability--
                                         | | |
-    q1 : -Rx(0.549)-Rz(0.878)-Rx(0.913)-X-C-Probability--
+        q1 : -Rx(0.549)-Rz(0.878)-Rx(0.913)-X-C-Probability--
 
-    T  : |    0    |    1    |    2    |3|4|Result Types|
+        T  : |    0    |    1    |    2    |3|4|Result Types|
     """
 
     def __init__(
@@ -150,7 +151,7 @@ def gradient(self, params: np.ndarray) -> np.ndarray:
 def _compute_kernel(px: np.ndarray, py: np.ndarray, sigma_list: List[float] = [0.1, 1]) -> float:
     r"""Gaussian radial basis function (RBF) kernel.
 
-    K(x, y) = sum_\sigma exp(-|x-y|^2/(2\sigma^2 ))
+    `K(x, y) = sum_\sigma exp(-|x-y|^2/(2\sigma^2 ))`
 
     Args:
         px (ndarray): Probability distribution
@@ -172,12 +173,12 @@ def mmd_loss(px: np.ndarray, py: np.ndarray, sigma_list: List[float] = [0.1, 1])
 
     MMD determines if two distributions are equal by looking at the difference between
     their means in feature space.
-
-    MMD(x, y) = | \sum_{j=1}^N \phi(y_j) - \sum_{i=1}^N \phi(x_i) |_2^2
+    ::
+        MMD(x, y) = | \sum_{j=1}^N \phi(y_j) - \sum_{i=1}^N \phi(x_i) |_2^2
 
     With a RBF kernel, we apply the kernel trick to expand MMD to
-
-    MMD(x, y) = \sum_{j=1}^N \sum_{j'=1}^N k(y_j, y_{j'})
+    ::
+        MMD(x, y) = \sum_{j=1}^N \sum_{j'=1}^N k(y_j, y_{j'})
                 + \sum_{i=1}^N \sum_{i'=1}^N k(x_i, x_{i'})
                 - 2 \sum_{j=1}^N \sum_{i=1}^N k(y_j, x_i)
 
diff --git a/src/braket/experimental/algorithms/simons/simons.py b/src/braket/experimental/algorithms/simons/simons.py
index 838cabd9..b0e67f95 100644
--- a/src/braket/experimental/algorithms/simons/simons.py
+++ b/src/braket/experimental/algorithms/simons/simons.py
@@ -25,11 +25,11 @@ def simons_oracle(secret_string: str) -> Circuit:
     """Quantum circuit implementing a particular oracle for Simon's problem.
 
     In the quantum setting, we first copy the input register into some
-    ancillary qubits: |x>|0> -> |x>|x>.
+    ancillary qubits: `|x>|0> -> |x>|x>`.
 
     We then perform the quantum analog of XOR, which means we apply an X gate
     to the kth qubit whenever the kth bit of `string` is 1. However, we only
-    apply this X gate when the flag qubit is also |1>. Thus, our X gate becomes
+    apply this X gate when the flag qubit is also `|1>`. Thus, our X gate becomes
     a CNOT gate between the flag qubit on the input register, and the kth qubit
     on the output.
 
diff --git a/tox.ini b/tox.ini
index ddfaa26d..d01486a6 100644
--- a/tox.ini
+++ b/tox.ini
@@ -51,10 +51,10 @@ basepython = python3
 skip_install = true
 deps =
     flake8
+    flake8-rst-docstrings
     git+https://github.com/aws/amazon-braket-build-tools.git
 commands =
     flake8 {posargs}
-    flake8 --enable-extensions=BCS src
 
 [testenv:isort]
 basepython = python3