diff --git a/docs/source/style.rst b/docs/source/style.rst index 20cfe20a2..a12a63c0f 100644 --- a/docs/source/style.rst +++ b/docs/source/style.rst @@ -428,3 +428,21 @@ There are two types of comments: *block* and *inline*. A good rule of thumb to f 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 +`_. +For additional grammar and usage guidance, +refer to `The Chicago Manual of Style `_. +A few notable guidelines: + + * Do not capitalize acronyms or inititalisms when defining them, + e.g., "computer-aided system engineering (CASE)," + "fast Fourier transform (FFT)." + +The source code (`.rst` files) for these pages +does not have a line-length guideline, +but line breaks inside text are encouraged.