2 files changed, 64 insertions, 57 deletions
diff --git a/README.md b/README.md
deleted file mode 100644
index 7bd2f0c..0000000
--- a/README.md
+++ /dev/null
@@ -1,57 +0,0 @@
-# `mdpoly` Multidimensional Polynomials
-
-Work in progress!
-
-## Quick Start
-
-There is still a big part of the API missing but the snipped below works enough
-to give an overview.
-
-```python
-from mdpoly import State, Variable, Parameter
-from mdpoly.representations import SparseRepr
-
-# Construct an expression
-x, y = Variable.from_names("x, y") # or just Variable("x")
-k = Parameter("k")
-
-p = (x + 2 * y) ** 3 + y ** 2 + k
-print(f"{p = }")
-
-# Make a concrete representation
-state = State(parameters={k: 3.14}) # try to replace with empty dict
-sparse, state = p.to_repr(SparseRepr, state)
-
-# Look inside the representation
-for entry in sparse.entries():
-    print(f"at (row, col) = {entry.row, entry.col} there is a polynomial:")
-    for term in sparse.terms(entry):
-        monomial_str = ""
-        for idx in term:
-            var = state.from_index(idx.var_idx)
-            monomial_str += f"{var.name}^{idx.power} "
-
-        # Get the coefficient
-        coeff = sparse.at(entry, term)
-        print(" - the monomial", monomial_str, "has coefficient", coeff)
-
-# You can also simply iterate over it
-for entry, term, coeff in sparse:
-    print(entry, term, coeff)
-```
-
-There is some advanced stuff that is still broken but the idea is that it will
-work soon (TM)
-
-```
-from mdpoly import Variable, MatrixVariable
-from mdpoly.types import Shape
-
-x = Variable("x")
-V = MatrixVariable("Q", Shape.column(3))
-
-print(x.shape, V.shape)
-
-z = x + V # error
-scalar = V.T @ V # no error (TODO)
-```
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..f4deb4d
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,64 @@
+``mdpoly`` or Multidimensional Polynomials
+==========================================
+
+*Work in progress!*
+
+Quick Start
+-----------
+
+There is still a big part of the API missing but the snipped below works enough
+to give an overview.
+
+.. code:: py
+
+        from mdpoly import State, Variable, Parameter
+        from mdpoly.representations import SparseRepr
+
+        # Construct an expression
+        x, y = Variable.from_names("x, y") # or just Variable("x")
+        k = Parameter("k")
+
+        p = (x + 2 * y) ** 3 + y ** 2 + k
+        print(f"{p = }")
+
+        # Expressions can be easily reparametrized
+        w = Parameter("w")
+        q = p.replace(y, w).replace(k, k ** 2) # createas a copy
+        print(f"{q = }")
+
+        # Make a concrete representation
+        state = State(parameters={k: 3.14}) # try to replace with empty dict
+        sparse, state = p.to_repr(SparseRepr, state)
+
+        # Look inside the representation
+        for entry in sparse.entries():
+            print(f"at (row, col) = {entry.row, entry.col} there is a polynomial:")
+            for term in sparse.terms(entry):
+                monomial_str = ""
+                for idx in term:
+                    var = state.from_index(idx.var_idx)
+                    monomial_str += f"{var.name}^{idx.power} "
+
+                # Get the coefficient
+                coeff = sparse.at(entry, term)
+                print(" - the monomial", monomial_str, "has coefficient", coeff)
+
+        # You can also simply iterate over it
+        for entry, term, coeff in sparse:
+            print(entry, term, coeff)
+
+There is some advanced stuff that is still broken but the idea is that it will
+work soon-ish.
+
+.. code:: py
+
+        from mdpoly import Variable, MatrixVariable
+        from mdpoly.types import Shape
+
+        x = Variable("x")
+        V = MatrixVariable("V", Shape.column(3))
+
+        print(x.shape, V.shape)
+
+        z = x + V # error
+        scalar = V.T @ V # no error (TODO)