Separate the user's documentation from the developer's documentation

docs/source/general_architecture.md

@@ -202,81 +202,10 @@ other_entity = another_namespace.SomeOtherEntity()
 ```
 
 ### Sessions
-The sessions are the interoperability classes that connect to where the data is stored. 
-In the case of wrappers, they take care of keeping consistency between the backends (e.g. databases) and the internal registry.
+The [sessions](./detailed_design.md#session) are the interoperability classes that connect to where the data is stored. 
+[In the case of wrappers](./wrapper_development.md#coding), they take care of keeping consistency between the backends (e.g. databases) and the internal registry.
 
-When you add an object to a wrapper, a copy of the object is created in the registry belonging to the session of the wrapper.
-
-To simplify the understanding and development of session classes, we have created a hierarchy:
-
-```eval_rst
-.. uml::
-  :caption: Simplified session inheritance scheme
-  :align: center
-
-  rectangle "OSP-core" as OSP {
-    abstract class Session {
-    }
-
-    class CoreSession implements Session {
-    }
-
-    abstract class WrapperSession extends Session {
-    }
-
-    class TransportSession implements WrapperSession {
-    }
-
-    abstract class DbWrapperSession extends WrapperSession {
-      commit()
-    }
-
-    abstract class SqlWrapperSession extends DbWrapperSession {
-    }
-
-    abstract class SimWrapperSession extends WrapperSession {
-      run()
-    }
-  }
-
-  rectangle "Sqlite wrapper" as sqlite {
-    class SqliteWrapperSession implements SqlWrapperSession {
-    }
-  }
-
-  rectangle "SqlAlchemy wrapper" as sqlalchemy {
-    class SqlAlchemyWrapperSession implements SqlWrapperSession {
-    }
-  }
-
-  rectangle "Simlammps wrapper" as simlammps {
-    class SimlammpsSession implements SimWrapperSession {
-    }
-  }
-
-  ' -----------------------
-  ' -------- NOTES --------
-  ' -----------------------
-    note as OSP.note_core
-      The CoreSession is the default
-      shared session for all Python objects
-    end note
-    OSP.note_core .. CoreSession
-
-    note as note_db
-      The db changes are persisted via
-      cuds_object.session.commit()
-    end note
-    note_db .. DbWrapperSession
-
-    note as OSP.note_sim
-      The simulation is run by calling
-      cuds_object.session.run()
-    end note
-    OSP.note_sim .. SimWrapperSession
-```
-
-As you can see, CoreSession is the default one used when instantiating a new object in your workspace.
+The `CoreSession` is the default one used when instantiating a new object in your workspace. When you add an object to a wrapper, a copy of the object is created in the registry belonging to the session of the wrapper.
 
 ## Wrappers
 Like we have mentioned in previous sections, wrappers allow the user to interact 

docs/source/index.md

@@ -79,7 +79,6 @@ SimPhoNy is an ontology-based open-source Python framework that promotes and ena
 
    jupyter/cuds-api.ipynb
    jupyter/sessions_and_vars.ipynb
-   detailed_design.md
    utils.md
    jupyter/multiple-wrappers.ipynb
    jupyter/simlammps.ipynb
@@ -117,6 +116,7 @@ SimPhoNy is an ontology-based open-source Python framework that promotes and ena
    :maxdepth: 2
 
    contribute.md
+   detailed_design.md
    links.md
    license.md
    Data protection <https://www.simphony-project.eu/en/data_protection.html>

docs/source/wrapper_development.md

@@ -96,6 +96,94 @@ This allows us to group and clearly define which components should and which one
  - [Syntactic layer](./detailed_design.md#syntactic-layer): 
    If none is available, one must be developed.
 
+To facilitate the creation of the session class on the interoperability layer, 
+there are several session abstract base classes that you can make your session
+inherit from, which already include some additional generic functions common to a few 
+typical applications: databases, triplestores and simulation engines.
+
+On the diagram below, you may observe a simplified session inheritance scheme 
+for OSP-core. As a wrapper developer, you will most probably want to inherit 
+from one of following abstract classes: `WrapperSession`, `DbWrapperSession`, 
+`TripleStoreWrapperSession`, `SqlWrapperSession`,  or `SimWrapperSession`. 
+Your new wrapper session would be located of the OSP-core box, 
+together among other wrapper sessions like the Simlammps, Sqlite or SqlAlchemy 
+sessions.
+
+```eval_rst
+.. uml::
+  :caption: Simplified session inheritance scheme
+  :align: center
+
+  rectangle "OSP-core" as OSP {
+    abstract class Session {
+    }
+
+    class CoreSession implements Session {
+    }
+
+    abstract class WrapperSession extends Session {
+    }
+
+    class TransportSession implements WrapperSession {
+    }
+
+    abstract class DbWrapperSession extends WrapperSession {
+      commit()
+    }
+
+    abstract class TripleStoreWrapperSession extends DbWrapperSession {
+    }
+
+    abstract class SqlWrapperSession extends TripleStoreWrapperSession {
+    }
+
+    abstract class SimWrapperSession extends WrapperSession {
+      run()
+    }
+  }
+
+  rectangle "Sqlite wrapper" as sqlite {
+    class SqliteWrapperSession implements SqlWrapperSession {
+    }
+  }
+
+  rectangle "SqlAlchemy wrapper" as sqlalchemy {
+    class SqlAlchemyWrapperSession implements SqlWrapperSession {
+    }
+  }
+
+  rectangle "Your wrapper" as yourwrapper {
+    class YourSession{
+    }
+  }
+
+  rectangle "Simlammps wrapper" as simlammps {
+    class SimlammpsSession implements SimWrapperSession {
+    }
+  }
+
+  ' -----------------------
+  ' -------- NOTES --------
+  ' -----------------------
+    note as OSP.note_core
+      The CoreSession is the default
+      shared session for all Python objects
+    end note
+    OSP.note_core .. CoreSession
+
+    note as note_db
+      The db changes are persisted via
+      cuds_object.session.commit()
+    end note
+    note_db .. DbWrapperSession
+
+    note as OSP.note_sim
+      The simulation is run by calling
+      cuds_object.session.run()
+    end note
+    OSP.note_sim .. SimWrapperSession
+```
+
 ## Engine installation
 Most engines will require some sort of compilation or installation before being able to use them through Python.