Introduce HACKING.rst so that anyone can pick up Ceygen development

HACKING.rst

@@ -0,0 +1,81 @@
+==================
+Ceygen Development
+==================
+
+This document should serve as a reminder to me and other possible Ceygen
+hackers about Ceygen coding style and conventions.
+
+Development Guidelines
+======================
+
+Some special and important files:
+
+ * ``eigen_cpp.h`` - low-level implementation of a tiny C++ Eigen subclass that
+   is used to create wrappers around Cython arrays.
+ * ``eigen_cython.pxd`` - exports BaseMap C++ class defined in `eigen_cpp.h`
+   to Cython along with other Eigen methods.
+ * ``dtype.{pxd,pyx}`` - defines the base scalar fused (template-like) type
+   that all other functions use, along with functions to create vectors and
+   matrices.
+ * ``dispatch.{h,pxd}`` - contains fancy code and Cython declarations for
+   so-called dispatchers: tiny helpers that call more optimized Eigen functions
+   (in fact, the same functions with different template parameters) for
+   column-contiguous, row-contiguous matrices and contiguous vectors.
+
+All other \*.{pxd,pyx} are public Ceygen modules.
+
+Please always use appropriate \*Dispatcher from `dispatch.pxd` instead of
+calling methods from `eigen_cython.pxd` directly, because declarations from
+`eigen_cython.pxd` don't contain ``except +`` keyword for performance reasons
+(i.e. you would leak C++ exceptions raised by Eigen code without converting
+them to Python exceptions).
+
+Tests and Stress Tests
+======================
+
+All public functions should have a unit test. Suppose you have a module
+``ceygen/modname.pyx``, then unit tests for all functions in ``modname.pyx``
+should go into ``ceygen/tests/test_modname.py``. There is a couple of
+"standard" environment variables recognized in tests:
+
+ * ``BENCHMARK`` - run potentially time-consuming benchmarks of Ceygen code
+ * ``BENCHMARK_NUMPY`` - also run some benchmarks with NumPy backend to see
+   difference
+ * ``SAVE`` - save timings into ``.pickle`` files that can be visualized by
+   ``support/visualize_stats.py``.
+
+Releasing Ceygen
+================
+
+Things to do when releasing new version (let it be **X.Y**) of Ceygen:
+
+Before Tagging
+--------------
+
+1. Set version to **X.Y** in `setup.py` (around line 37)
+#. Ensure `ChangeLog.rst` mentions all important changes
+#. Ensure that `README.rst` is up-to-date
+#. (Optional) update **short description** in `setup.py`
+#. (Optional) update **long description** `README.rst`
+
+Tagging & Publishing
+--------------------
+
+1. Do ``./setup.py sdist`` and check contents, unpack somewhere, run tests incl.
+   benchmarks
+#. git tag -s **vX.Y**
+#. ./setup.py register sdist upload
+#. Build and upload docs: ``cd ../ceygen-doc && ./synchronize.sh``
+#. If **short description** changed, update it manually at following places:
+
+   * https://github.com/strohel/Ceygen
+#. If **long description** changed, update it manually at following places:
+
+   * http://scipy.org/Topical_Software
+   * http://www.ohloh.net/p/ceygen
+
+After
+-----
+
+1. Set version to **$NEXT_VERSION-pre** in `setup.py`
+#. Add header for the next version into `ChangeLog.rst`

README.rst

@@ -74,8 +74,8 @@ On the other hand, Ceygen...
   infrastructure - implementing a new function should be rather straightforward (with
   decent Cython and C++ knowledge). We're very open to pull requests!
   (do include unit tests in them)
-* **needs recent Cython** to compile. [#cythonvers]_ If this is a problem, you can
-  distribute .cpp files or final Python extension module instead.
+* **needs recent Cython** (currently at least 0.19.1) to compile. If this is a problem,
+  you can distribute .cpp files or final Python extension module instead.
 * **doesn't bring Eigen's elegance to Cython** - if you think of lazy evaluation and
   advanced expessions, stop dreaming. Ceygen will make your code faster, not nicer.
   `Array expessions`_ will help here.
@@ -181,7 +181,3 @@ Please report any bugs you find and suggestions you may have to `Ceygen's github
 Tracker`_.
 
 .. _`Ceygen's github Issue Tracker`: https://github.com/strohel/Ceygen/issues
-
-.. rubric:: Footnotes
-
-.. [#cythonvers] currently this is at least Cython 0.18.

doc/HACKING.rst

@@ -0,0 +1 @@
+../HACKING.rst

doc/index.rst

@@ -12,6 +12,7 @@ Ceygen API Documentation
    lu
    llt
    reductions
+   HACKING
 
 Indices and tables
 ==================