Refactored Caching, Refactored BnfNodeParser, Introduced Sphinx

docs/source/blog/concepts.rst

@@ -0,0 +1,42 @@
+Concepts
+========
+
+
+
+Basic definition
+****************
+To define a new concept
+
+::
+
+    > def concept hello a as "hello" + a
+
+
+Note that if the left part of the keyword 'as', the traditional quotes that would surround 'hello' and 'a' are not necessary.
+In this example 'a' is a variable, as it appears as variable in the 'as' section (while hello
+appears as a string)
+
+You have just defined a concept name 'hello'. Sheerka now can understand
+
+>>> hello kodjo
+>>> hello my friend
+
+When you do so, an instance of the concept will be created in memory. In the first case,
+it will a variable ``'a'`` filled with the value ``'kodjo'``, in the second case, the variable
+will be filled with the value ``'my friend'``
+
+
+Another example:
+
+::
+
+    > def concept one as 1
+    > def concept two as 2
+    > def concept a plus b as a + b
+
+That's enough to define the addition
+
+>>> one plus two
+3
+
+

docs/source/blog/persistence.rst

@@ -0,0 +1,92 @@
+Data Persistence
+=================
+
+
+The basic idea
+""""""""""""""
+
+Everything starts with a basic and simple idea. 
+
+My simple idea for the persistence is that **everything** should be persisted.
+The actual main difference between an human being and a computer is that we have the
+ability to remember almost everything (at least everything that we have not forgotten).
+
+On the contrary, we only allow computer to remember specific stuff that we thing (as of
+today) will be relevant in the future.
+
+There are two majors issues with that:
+
+1. The obvious one, is that we don't know what will be needed in the future
+2. We prevent the computer to remember things like an human being would do
+
+I think I will come back to the second point some day as it's more subtle than it looks like
+(at least to me).
+
+Anyway, I need 
+
+1. A persistence mechanism that can save my main object (**Concepts**, as well as the **Events** or the **Rules**), but also the current state of the system.
+2. I also need to have the ability do bo back in time, to see what were the values of theses objects in the past.
+3. And of course, I need traceability on theses objects. Eg, the ability to prove that the data was not altered not corrupted
+
+
+
+There are tons of different databases already on the market. Unfortunately for me, I'm not
+a database expert. But, I already know that I was not looking for a traditional
+relational database (SGDB) as the structure will evolve and I didn't want to spend
+my time on redesigning the schemas and the constraints.
+
+.. _git: https://git-scm.com/
+
+As I was learning Python, it could have been a good idea to also start looking at an
+already existing NoSql database. I started to look at MongoDB, but I got lazy. I knew that
+the top feature that I needed was that management of the history (the way git_ does it),
+and it was not provided by Mongo, or I didn't notice it in my first readings on the subject.
+
+So I decided to design and implement my own database.
+
+
+Versioning the information
+"""""""""""""""""""""""""""""""""""""
+As I said previously, I want a system that mimics how git_ versions its objects.
+
+::
+
+   Obj v0 :  parents = []
+            user name = <a name>
+            modification date = <a date>
+            digest = xxxxx
+
+    Obj v1: parents = [xxxxx]
+            user name = <a name>
+            modification date = <a date>
+            digest = yyyyy
+
+    Obj v1: parents = [yyyyy]
+            user name = <a name>
+            modification date = <a date>
+            digest = zzzzz
+
+    and so on...
+
+I always keep a reference to the last version of the object, so I can navigate through
+the versions using the ``parents`` attribute of the object
+
+In git_, there are basically two types of objects :
+
+- **content** (file content, or directory structure)
+- **reference** to content (commit or tags)
+
+The hash a **content** only depends on it, while the hash of a **reference** also depends
+on the user name, the modification date and the parents. In both cases, the hash is
+computed on the whole object. So the hash can also be used to check the integrity
+of an object.
+
+For my objects, I need to decide how I compute the hash.
+
+**Concepts** have history, if I decide to include the history in the hash,
+as the modification date is :code:`datetime.now()`, a new version will be created
+even if the **Concept** has not changed. If I don't include it, the integrity of the
+what is saved is no longer guaranteed.
+
+I choose to value identity over integrity. The hash code of the **Concepts** does not depend
+on his history. We will see what the future will say about this.

docs/source/conf.py

@@ -0,0 +1,55 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Sheerka'
+copyright = '2020, Kodjo Sossouvi'
+author = 'Kodjo Sossouvi'
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.1'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,30 @@
+Sheerka's documentation!
+===================================
+
+Hi, welcome the the documentation page of Sheerka. 
+There will be two types of documentation
+   
+   * The first one will be more like a blog, where I will express my feelings ;-)
+   * A more standard Technical Design documentation (if it does not take too much time :-)
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Blog:
+
+   blog/blog
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Technical Design:
+
+   tech/tech
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/tech/tech.rst

@@ -0,0 +1,4 @@
+Technical Design
+================
+
+I need to put some stuff here