From e708b535dd508993c2c58dbf552d9acc47d23e49 Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Mon, 10 Oct 2016 12:12:38 -0400
Subject: [PATCH] More "easy" docs work in matrices.py/options.py.

---
 src/dunshire/matrices.py | 29 +++++++++++++++++++++++++++--
 src/dunshire/options.py  | 27 +++++++++++++++++----------
 2 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/src/dunshire/matrices.py b/src/dunshire/matrices.py
index 38d4afe..3670d8f 100644
--- a/src/dunshire/matrices.py
+++ b/src/dunshire/matrices.py
@@ -9,15 +9,24 @@ from cvxopt.lapack import syev
 
 import options
 
+
 def append_col(left, right):
     """
-    Append the matrix ``right`` to the right side of the matrix ``left``.
+    Append two matrices side-by-side.
 
     Parameters
     ----------
+
     left, right : matrix
         The two matrices to append to one another.
 
+    Returns
+    -------
+
+    matrix
+        A new matrix consisting of ``right`` appended to the right
+        of ``left``.
+
     Examples
     --------
 
@@ -39,15 +48,23 @@ def append_col(left, right):
     """
     return matrix([left.trans(), right.trans()]).trans()
 
+
 def append_row(top, bottom):
     """
-    Append the matrix ``bottom`` to the bottom of the matrix ``top``.
+    Append two matrices top-to-bottom.
 
     Parameters
     ----------
+
     top, bottom : matrix
         The two matrices to append to one another.
 
+    Returns
+    -------
+
+    matrix
+        A new matrix consisting of ``bottom`` appended below ``top``.
+
     Examples
     --------
 
@@ -84,9 +101,15 @@ def eigenvalues(symmat):
     symmat : matrix
         The real symmetric matrix whose eigenvalues you want.
 
+    Returns
+    -------
+
+    list of float
+       A list of the eigenvalues (in no particular order) of ``symmat``.
 
     Raises
     ------
+
     TypeError
         If the input matrix is not symmetric.
 
@@ -129,6 +152,7 @@ def identity(domain_dim):
 
     Returns
     -------
+
     matrix
         A ``domain_dim``-by-``domain_dim`` dense integer identity matrix.
 
@@ -163,6 +187,7 @@ def inner_product(vec1, vec2):
 
     Returns
     -------
+
     float
         The inner product of ``vec1`` and ``vec2``.
 
diff --git a/src/dunshire/options.py b/src/dunshire/options.py
index 03518d8..4349154 100644
--- a/src/dunshire/options.py
+++ b/src/dunshire/options.py
@@ -2,17 +2,24 @@
 A place to collect the various options that "can be passed to the
 underlying engine." Just kidding, they're constants and you can't
 change them. But this makes the user interface real simple.
-"""
 
-# The absolute tolerance used in all "are these numbers equal" and "is
-# this number less than (or equal to) that other number" tests.
-ABS_TOL = 1e-7
+.. data:: ABS_TOL
 
-# The default output format for floating point numbers. It has been
-# chosen to match the ABS_TOL, in the sense that if x != y, then they
-# would not appear different when printed.
-FLOAT_FORMAT = '%.7f'
+    The absolute tolerance used in all "are these numbers equal" and "is
+    this number less than (or equal to) that other number" tests.
+
+.. data:: FLOAT_FORMAT
+
+    The default output format for floating point numbers. It has been
+    chosen to match the ``ABS_TOL``, in the sense that if ``x != y``,
+    then they would not appear different when printed.
 
-# The underlying CVXOPT solver can output debug information, and I
-# guess, so could we. But we don't want to because it's ugly.
+.. data:: VERBOSE
+
+    The underlying CVXOPT solver can output debug information, and I
+    guess, so could we. But we don't want to because it's ugly.
+
+"""
+ABS_TOL = 1e-7
+FLOAT_FORMAT = '%.7f'
 VERBOSE = False
-- 
2.43.2