README: convert to reStructuredText

This is a python project, so we might as well use the standard
documentation format.

diff --git a/README b/README
deleted file mode 100644 (file)
index 8248b9c..0000000
--- a/README
+++ /dev/null
@@ -1,70 +0,0 @@
-This directory contains all of the tests for the claims in the paper,
-as well as the supporting code. It has a few requirements:
-
-  * Python built with support for sqlite
-  * SymPy <https://pypi.org/project/sympy/>
-  * MessagePack for python <https://pypi.org/project/msgpack/>
-
-Here is a quick summary of the files:
-
-  * compute.py - utilities for computing all cones, ranks of Lorentz
-    cones, etc. and storing them in a database. These are long-
-    running computations, not otherwise used by the test suite.
-
-  * cones.py - the SymmetricCone class and its subclasses L, HR, HC,
-    HH, and HO.
-
-  * live.db - an empty (until you fill it) SQLite database for storing
-    the cones/ranks computed by the functions in compute.py.
-
-    HINT: unless you want "git diff" to take forever and tempt you to
-    commit gigabytes of binary junk to the repo, you should tell git
-    (insofar as is possible) to ignore changes to the live database:
-
-      $ git update-index --assume-unchanged tests/live.db
-      $ git update-index --skip-worktree tests/live.db
-
-  * partitions.py - functions relating to integer partitions.
-
-  * sql.py - functions for working with the SQL database.
-
-  * tests.py - the main tests for the results in the paper.
-
-  * verify-live-db.py - a runnable script that will inspect live.db to
-    make sure there is enough (consistent) data there.
-
-Every function (not just the results in the paper) is itself
-tested. To run the entire test suite, you can run
-
-  $ python -m doctest *.py
-
-from within this directory. To populate the live database, there are
-two things to do. First, run compute.py:
-
-  $ python compute.py
-  computing cones of dimension 0...
-  computing cones of dimension 1...
-
-This will start computing all symmetric cones, up to isomorphism, in
-dimension=1,2,.... successively. It will take a very long time and
-eventually consume all of your RAM. Hit Ctrl-C when you get scared,
-and it will stop. The cones are saved to the database at each step, so
-killing the program will only abandon the computation for the current
-dimension (not all previous dimensions).
-
-In addition to the cones, you will also want to compute some Lyapunov
-ranks corresponding to Lorentz cones. For that, the same compute.py
-is used, but you have to pass it "lorentz" as the first argument on
-the command-line:
-
-  $ python compute.py lorentz
-  computing lorentz ranks in dimension 0...
-  computing lorentz ranks in dimension 1...
-
-Again, hit Ctrl-C when you get bored. Afterwards your live.db will
-hopefully contain enough data to check the results in the paper.
-Running,
-
-  $ python verify-live-db.py
-
-will confirm it.

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..bbe4087
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,81 @@
+This repository contains tests and supporting code for the claims in
+the paper *The uniqueness of Lyapunov rank among symmetric cones* by
+Michael Orlitzky and Giovanni Barbarino. It has a few requirements:
+
+* Python built with support for sqlite
+* `SymPy <https://pypi.org/project/sympy/>`_
+* `MessagePack <https://pypi.org/project/msgpack/>`_ for python
+
+Here is a quick summary of the files:
+
+* **compute.py** - utilities for computing all cones, ranks of Lorentz
+  cones, etc. and storing them in a database. These are long-
+  running computations, not otherwise used by the test suite.
+
+* **cones.py** - the ``SymmetricCone`` class and its subclasses ``L``,
+  ``HR``, ``HC``, ``HH``, and ``HO``.
+
+* **live.db** - an empty (until you fill it) SQLite database for
+  storing the cones/ranks computed by the functions in compute.py.
+
+  HINT: unless you want "git diff" to take forever and tempt you to
+  commit gigabytes of binary junk to the repo, you should tell git
+  (insofar as is possible) to ignore changes to the live database:
+
+  .. code-block:: console
+
+      $ git update-index --assume-unchanged live.db
+      $ git update-index --skip-worktree live.db
+
+* **partitions.py** - functions relating to integer partitions.
+
+* **sql.py** - functions for working with the SQL database.
+
+* **tests.py** - the main tests for the results in the paper.
+
+* **verify-live-db.py** - a runnable script that will inspect live.db
+  to make sure there is enough (consistent) data there.
+
+Every function (not just the results in the paper) is itself
+tested. To run the entire test suite, you can run
+
+.. code-block:: console
+
+  $ python -m doctest *.py
+
+from within this directory. To populate the live database, there are
+two things to do. First, run compute.py:
+
+.. code-block:: console
+
+  $ python compute.py
+  computing cones of dimension 0...
+  computing cones of dimension 1...
+
+This will start computing all symmetric cones, up to isomorphism, in
+dimension=1,2,.... successively. It will take a very long time and
+eventually consume all of your RAM. Hit Ctrl-C when you get scared,
+and it will stop. The cones are saved to the database at each step, so
+killing the program will only abandon the computation for the current
+dimension (not all previous dimensions).
+
+In addition to the cones, you will also want to compute some Lyapunov
+ranks corresponding to Lorentz cones. For that, the same compute.py
+is used, but you have to pass it "lorentz" as the first argument on
+the command-line:
+
+.. code-block:: console
+
+  $ python compute.py lorentz
+  computing lorentz ranks in dimension 0...
+  computing lorentz ranks in dimension 1...
+
+Again, hit Ctrl-C when you get bored. Afterwards your live.db will
+hopefully contain enough data to check the results in the paper.
+Running,
+
+.. code-block:: console
+
+  $ python verify-live-db.py
+
+will confirm it.