Add basic documentation

Makefile

@@ -86,7 +86,8 @@ test36: .venv/py36/bin/py.test ## run tests for Python 3.6
 
 test37: .venv/py37/bin/py.test ## run tests for Python 3.7
 	$(TESTENV) $< -v $(TESTOPTIONS) src tests docs/*.rst
-.venv/py37/bin/sphinx-build: .venv/py37/bin/py.test
+
+.venv/py36/bin/sphinx-build: .venv/py36/bin/py.test
 
 docs: .venv/py36/bin/sphinx-build ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs SPHINXBUILD=../.venv/py36/bin/sphinx-build clean

README.rst

@@ -26,15 +26,33 @@ The newtonprop Python package
 
 Pure Python reference implementation of the Newton propagator for quantum dynamics.
 
-Development of `newtonprop` happens on `Github`_.
+The Newton propagator evaluates an expansion of the time evolution operator
+:math:`e^{-i \Op{H} dt}` or :math:`e^{\Liouville dt}` in Newton polynomials,
+using an implicitly restarted Arnoldi scheme. More generally, it can evaluate
+the application of any operator-valued function to a state.
+
+Development of the ``newtonprop`` package happens on `Github`_.
 You can read the full documentation at `ReadTheDocs`_.
 
+.. Warning::
+
+    This is a reference implementation only. It aims to be easy to understand,
+    so that that it can guide the implementation of the algorithm in a compiled
+    language, and to provide a baseline against which to test such an
+    implementation. Being written in pure Python, it runs several orders of
+    magnitude slower than an implementation in a compiled language. Thus, it
+    cannot compete e.g. with the `ODE solvers provided by SciPy`_ (which run at
+    C speed), even though the Newton propagator is usually expected to be
+    superior in runtime, memory usage, and precision.
+
 
 .. _ReadTheDocs: https://newtonprop.readthedocs.io/en/latest/
+.. _ODE solvers provided by SciPy: https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.integrate.ode.html
 
 
 Installation
 ------------
+
 To install the latest released version of ``newtonprop``, run this command in your terminal:
 
 .. code-block:: console
@@ -43,14 +61,14 @@ To install the latest released version of ``newtonprop``, run this command in yo
 
 This is the preferred method to install ``newtonprop``, as it will always install the most recent stable release.
 
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
+If you don't have `pip`_ installed, the `Python installation guide`_ can guide
 you through the process.
 
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
 
-To install the latest development version of ``newtonprop`` from `Github`_.
+To install the latest development version of ``newtonprop`` from `Github`_:
 
 .. code-block:: console
 

docs/_static/mycss.css

@@ -16,4 +16,24 @@ div.figure p.caption {
 
 div.section p {
     clear: left;
-}
+}
+
+/* fix equation numbers in RTD */
+
+span.eqno {
+    float: right;
+     margin-left: 5px;
+}
+
+.headerlink {
+    display: none;
+    visibility: hidden;
+}
+.headerlink::after{
+    visibility: visible;
+    display: inline-block;
+}
+.headerlink::hover{
+    display: inline-block;
+    visibility: visible;
+}

docs/conf.py

@@ -55,14 +55,13 @@ def run_apidoc(_):
     'sphinx.ext.extlinks',
     'sphinx.ext.ifconfig',
     'sphinx.ext.todo',
-    'sphinx.ext.inheritance_diagram',
     'dollarmath',
+    'nbsphinx',
+    'sphinx.ext.inheritance_diagram',
     'sphinx_autodoc_typehints',
+    'sphinxcontrib.bibtex',
 ]
 
-extensions.append('nbsphinx')
-
-
 if os.getenv('SPELLCHECK'):
     extensions += 'sphinxcontrib.spelling',
     spelling_show_suggestions = True
@@ -76,6 +75,7 @@ def run_apidoc(_):
     'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'matplotlib': ('https://matplotlib.org/', None),
+    'qutip': ('http://qutip.org/docs/latest/', None),
 }
 
 # Add any paths that contain templates here, relative to this directory.
@@ -127,6 +127,8 @@ def run_apidoc(_):
             'diag': ['{\\operatorname{diag}}', 0],
             'abs': ['{\\operatorname{abs}}', 0],
             'pop': ['{\\operatorname{pop}}', 0],
+            'ee': ['{\\text{e}}', 0],
+            'ii': ['{\\text{i}}', 0],
             'aux': ['{\\text{aux}}', 0],
             'opt': ['{\\text{opt}}', 0],
             'tgt': ['{\\text{tgt}}', 0],
@@ -154,6 +156,9 @@ def run_apidoc(_):
             'AbsSq': ['{\\left\\vert#1\\right\\vert^2}', 1],
             'Re': ['{\\operatorname{Re}}', 0],
             'Im': ['{\\operatorname{Im}}', 0],
+            'Real': ['{\\mathbb{R}}', 0],
+            'Complex': ['{\\mathbb{C}}', 0],
+            'Integer': ['{\\mathbb{N}}', 0],
         }
     }
 }

docs/index.rst

@@ -31,6 +31,7 @@ Welcome to the newtonprop's Python package's documentation!
    contributing
    authors
    history
+   newton
    example.ipynb