From 27d01aba16e924430b47a804b830ec72f1bcf0c5 Mon Sep 17 00:00:00 2001
From: Mike McCann <57153404+Michael-T-McCann@users.noreply.github.com>
Date: Fri, 22 Oct 2021 09:39:37 -0700
Subject: [PATCH] Add a style guide for grammar to our style documentation
 (#49)

* Add grammar style guide

* Add line length, additional guidelines

* Fix space after equation, rst warnings
---
 docs/source/functional.rst |  2 +-
 docs/source/op_linop.rst   |  2 +-
 docs/source/style.rst      | 28 ++++++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/source/functional.rst b/docs/source/functional.rst
index 6bf31f129..54c03a830 100644
--- a/docs/source/functional.rst
+++ b/docs/source/functional.rst
@@ -46,7 +46,7 @@ An instance of :class:`.Functional`, ``f``, may provide three core operations.
 * Proximal operator
    - ``f.prox(v, lam)`` returns the result of the scaled proximal operator
      at ``v`` with scale ``lam``.
-   -  The proximal operator of a functional :math:`f : \mathbb{R}^n \to \mathbb{R}` is the mapping
+   - The proximal operator of a functional :math:`f : \mathbb{R}^n \to \mathbb{R}` is the mapping
      :math:`\mathrm{prox}_f : \mathbb{R}^n \times \mathbb{R} \to \mathbb{R}^n` defined as
 
      .. math::
diff --git a/docs/source/op_linop.rst b/docs/source/op_linop.rst
index 54ad98419..39b3a5175 100644
--- a/docs/source/op_linop.rst
+++ b/docs/source/op_linop.rst
@@ -189,7 +189,7 @@ we have
 
 
 Defining A New Linear Operator
------------------------------
+------------------------------
 
 To define a new linear operator,
 pass a callable to the :class:`.LinearOperator` constructor
diff --git a/docs/source/style.rst b/docs/source/style.rst
index 7eee6af14..1d441bd29 100644
--- a/docs/source/style.rst
+++ b/docs/source/style.rst
@@ -423,3 +423,31 @@ An example of this is complicated operations which most likely require a block o
     i = i & (i-1) == 0:  # true if i is 0 or a power of 2 [explains the concept not the code]
 
 If a comment consists of one or more full sentences (as is typically the case for *block* comments), it should start with an upper case letter and end with a period. *Inline* comments often consist of a brief phrase which is not a full sentence, in which case they should have a lower case initial letter and not have a terminating period.
+
+Documentation Pages
+-------------------
+Documentation that is separate from code (like this page)
+should follow the
+`IEEE Style Manual
+<https://journals.ieeeauthorcenter.ieee.org/your-role-in-article-production/ieee-editorial-style-manual/>`_.
+For additional grammar and usage guidance,
+refer to `The Chicago Manual of Style <https://www.chicagomanualofstyle.org/>`_.
+A few notable guidelines:
+
+    * Equations which conclude a sentence should end with a period,
+      e.g., "Poisson's equation is
+
+      .. math::
+
+       \Delta \varphi = f \;."
+
+    * Do not capitalize acronyms or inititalisms when defining them,
+      e.g., "computer-aided system engineering (CASE),"
+      "fast Fourier transform (FFT)."
+
+    * Avoid capitalization in text except where absolutely necessary,
+      e.g., "Newton’s first law."
+
+
+The source code (`.rst` files) for these pages does not have a line-length guideline,
+but line breaks at or before 79 characters are encouraged.