Refactored Caching, Refactored BnfNodeParser, Introduced Sphinx
This commit is contained in:
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = source
|
||||
BUILDDIR = build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@@ -0,0 +1,35 @@
|
||||
@ECHO OFF
|
||||
|
||||
pushd %~dp0
|
||||
|
||||
REM Command file for Sphinx documentation
|
||||
|
||||
if "%SPHINXBUILD%" == "" (
|
||||
set SPHINXBUILD=sphinx-build
|
||||
)
|
||||
set SOURCEDIR=source
|
||||
set BUILDDIR=build
|
||||
|
||||
if "%1" == "" goto help
|
||||
|
||||
%SPHINXBUILD% >NUL 2>NUL
|
||||
if errorlevel 9009 (
|
||||
echo.
|
||||
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||
echo.may add the Sphinx directory to PATH.
|
||||
echo.
|
||||
echo.If you don't have Sphinx installed, grab it from
|
||||
echo.http://sphinx-doc.org/
|
||||
exit /b 1
|
||||
)
|
||||
|
||||
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
goto end
|
||||
|
||||
:help
|
||||
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||
|
||||
:end
|
||||
popd
|
||||
@@ -1,4 +1,10 @@
|
||||
.. contents::
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
concepts
|
||||
parsers
|
||||
persistence
|
||||
|
||||
|
||||
2019-10-30
|
||||
**********
|
||||
@@ -55,35 +61,12 @@ An **history** is a triplet of
|
||||
.. _git: https://git-scm.com/
|
||||
|
||||
Personally, i have taken this way of tracking modification from how it's done on git_,
|
||||
I guess Linux Torvarlds took it from somewhere.
|
||||
I guess Linux Torvalds took it from somewhere.
|
||||
|
||||
|
||||
2019-10-31
|
||||
**********
|
||||
|
||||
More on Concepts
|
||||
""""""""""""""""
|
||||
To define a new concept
|
||||
|
||||
::
|
||||
|
||||
def concept hello a as "hello" + a
|
||||
|
||||
|
||||
Note that 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)
|
||||
|
||||
So, you could call the concept by
|
||||
|
||||
::
|
||||
|
||||
hello kodjo
|
||||
hello my friend
|
||||
|
||||
They will produce the strings "hello kodjo" or "hello my friend"
|
||||
|
||||
About versionning of the information
|
||||
About versioning of the information
|
||||
"""""""""""""""""""""""""""""""""""""
|
||||
As I said previously, I mimic how git_ versions its objects.
|
||||
|
||||
@@ -161,27 +144,7 @@ For example, for the exercise called "The descent" you will find
|
||||
|
||||
It will be great if Sheerka is able to produce some code from these instructions :-)
|
||||
|
||||
Some words on data persistence
|
||||
"""""""""""""""""""""""""""""""""""""""""
|
||||
As I previously said (or not), the main difference between Sheerka and other languages,
|
||||
is that Sheerka has a memory of its (her ? :-) previous interactions with the users.
|
||||
|
||||
The **Concepts**, as well as the **Events** or the **Rules** are persisted. Because of
|
||||
that, I think that the more Sheerka is used, the more easier it will be to use it.
|
||||
|
||||
So my first focus was to decide which database to use.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
SheerkaDataProvider (sdp)
|
||||
@@ -1130,3 +1093,10 @@ include <=, >=, = and != as well, once for all. Sorting things according to thes
|
||||
human naturally do.
|
||||
|
||||
|
||||
2020-05-01
|
||||
**********
|
||||
|
||||
Blog
|
||||
""""""
|
||||
Hi, I have the feeling that I am almost there with the parsers part. I have
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -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']
|
||||
@@ -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`
|
||||
@@ -0,0 +1,4 @@
|
||||
Technical Design
|
||||
================
|
||||
|
||||
I need to put some stuff here
|
||||
Reference in New Issue
Block a user