README: convert to reStructuredText, and rewrite

This will look nice on Codeberg, and in any case it's nice to have
some meaningful information in here.

diff --git a/README b/README
deleted file mode 100644 (file)
index e7c660d..0000000
--- a/README
+++ /dev/null
@@ -1,11 +0,0 @@
-My personal library of SageMath code
-
-If you symlink it to ~/.sage/init.sage, the sample init.sage file will
-load this stuff into your session when Sage starts. It assumes that
-this repository lives at either ~/src/sage.d or ~/src/sage.d.git, but
-that's easy to change. More likely though you will want to copy/paste
-the relevant parts into your own personal (preexisting) init.sage.
-
-Newer versions of Sage don't load ~/.sage/init.sage during test mode,
-and all modules need to be imported explicitly. The test suite is
-therefore a little tricky to run; but "make check" should work.

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..92e9ab2
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,72 @@
+Personal library of `SageMath <https://www.sagemath.org/>`_ code
+
+Overview
+========
+
+This is where I keep SageMath routines that have proven useful in the
+long term, but have not been upstreamed yet. Parts of it are stable,
+and some parts change every day. YMMV, caveat emptor, etc.
+
+Honorable mentions:
+
+mjo.clan
+  Implementation of clans (real, finite dimensional
+  compact left-symmetric algebras) a la Vinberg.
+mjo.cone
+  Miscellaneous functions on convex cones. Things wind up
+  here if they're useful but don't fit nicely into the Sage
+  abstraction.
+mjo.eja
+  Implementation of Euclidean Jordan algebras a la Faraut and Korányi.
+  (There is a draft of a book on my website that makes use of this.)
+mjo.hurwitz
+  Octonions, and matrix algebras over the four famous Euclidean
+  Hurwitz algebras (R,C,H,O).
+mjo.matrix_algebra
+  Matrices whose entries and scalars can come from different rings.
+mjo.symbol_sequence
+  Indexed symbolic expressions, for e.g. the entries of a matrix
+  of arbitrary size.
+
+
+Installation
+============
+
+Append the path to this repository to your `PYTHONPATH
+<https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH>`_,
+either in the script that you use to launch Sage, or in your shell
+initialization file (``~/.bashrc`` if you use BASH). For example,
+
+.. code-block:: shell
+
+  PYTHONPATH="${PYTHONPATH}:/path/to/sage.d.git"
+
+If you would like the public bits of the library to be automatically
+imported when you start Sage, add
+
+.. code-block:: python
+
+  from mjo.all import *
+
+to ``~/.sage/init.sage``. If you don't have an ``~/.sage/init.sage``
+file, and if you don't mind any of my ipython preferences, feel free
+to symlink the one included with the repository:
+
+.. code-block:: shell
+
+  $ ln -s /path/to/repo/init.sage ~/.sage/init.sage
+
+
+Testing
+=======
+
+Newer versions of Sage don't load ``~/.sage/init.sage`` while testing,
+so all modules need to be imported explicitly in the doctests. Aside
+from that, the tests work like any other Sage code. There is a ``make
+check`` target defined in the ``makefile`` for convenience, but
+
+.. code-block:: shell
+
+  $ python -m sage.doctest file/to/test.py
+
+should work so long as your ``PYTHONPATH`` is configured properly.