Add documentation in README

Since there's no more decent documentation hosting service, use GitHub
via the README.

Signed-off-by: Matteo Cafasso <noxdafox@gmail.com>

README.rst

@@ -5,7 +5,7 @@ CLIPS Python bindings
    :target: https://travis-ci.org/noxdafox/clipspy
    :alt: Build Status
 
-Python CFFI bindings for CLIPS_ 6.30.
+Python CFFI_ bindings for CLIPS_ 6.30
 
 Installation
 ------------
@@ -18,6 +18,91 @@ If library and headers are not in the system default locations, they can be spec
 
     # CFLAGS="-I<headers path>" LDFLAGS="-L<library path>" pip install pyclips
 
+Design principles
+-----------------
+
+The clipspy bindings aim to be a "pythonic" thin layer built on top of the CLIPS native C APIs. Most of the functions and the methods directly resolve to the CLIPS functions documented in the `Advanced Programming Guide`_.
+
+Python standard paradigms are preferred such as property getters and setters, generators and magic methods.
+
+Data types
+----------
+
+The mapping between CLIPS and Python types is as follows.
+
++------------------+------------+
+| CLIPS            | Python     |
++==================+============+
+| INTEGER          | int        |
++------------------+------------+
+| FLOAT            | float      |
++------------------+------------+
+| STRING           | str        |
++------------------+------------+
+| SYMBOL           | Symbol *   |
++------------------+------------+
+| MULTIFIELD       | list       |
++------------------+------------+
+| FACT_ADDRESS     | Fact **    |
++------------------+------------+
+| INSTANCE_ADDRESS | Instance   |
++------------------+------------+
+| EXTERNAL_ADDRESS | ffi.CData  |
++------------------+------------+
+
+\* The Python Symbol object is a `interned string`_
+
+** `ImpliedFact` and `TemplateFact` are `Fact` subclasses
+
+Namespaces
+----------
+
+To keep the ``Environment`` interface simple, the CLIPS functions have been grouped into five different namespaces. Each namespace is accessible via an ``Environment`` specific attribute.
+
+* ``Environment.facts``: facts and templates
+* ``Environment.agenda``: rules and activations
+* ``Environment.classes``: classes and instances
+* ``Environment.modules``: modules and global variables
+* ``Environment.functions``: functions, generics and methods
+
+
+Objects lifecycle
+-----------------
+
+All clipspy objects are simple wrappers of CLIPS data structures. This means every object lifecycle is bound to the CLIPS data structure it refers to.
+
+In most of the cases, deleting or undefining an object makes it unusable.
+
+Example:
+
+.. code:: python
+
+    template = env.facts.find_template('some-fact')
+
+    # remove the Template from the CLIPS Environment
+    template.undefine()  # from here on, the template object is unusable
+
+    # this will cause an error
+    print(template)
+
+If the previous example is pretty straightforward, there are more subtle scenarios.
+
+.. code:: python
+
+    templates = tuple(env.facts.templates())
+
+    # remove all CLIPS constructs from the environment
+    env.clear()  # from here on, all the previously created objects are unusable
+
+    # this will cause an error
+    for template in templates:
+        print(template)
+
+API Documentation
+-----------------
+
+The ``doc`` folder contains the sources to generate the documentation via ``sphinx``.
+
 Example
 -------
 
@@ -58,9 +143,7 @@ Example
     # execute the activations in the agenda
     environment.agenda.run()
 
-Documentation
--------------
-
-The ``doc`` folder contains the sources to generate the documentation via ``sphinx``.
-
 .. _CLIPS: http://www.clipsrules.net/
+.. _CFFI: https://cffi.readthedocs.io/en/latest/index.html
+.. _`Advanced Programming Guide`: http://clipsrules.sourceforge.net/documentation/v630/apg.pdf
+.. _`interned string`: https://docs.python.org/3/library/sys.html?highlight=sys%20intern#sys.intern