DOC WIP: Structure documentation.

src/doc/conf.py

@@ -190,6 +190,10 @@ epub_exclude_files = ['search.html']
 #     '<namespace_here>' : ('<base_url_here>', 'javadoc'),
 # }
 
+javadoc_url_map = {
+    'org.restlet': ('https://javadocs.restlet.talend.com/2.4/jse/api', 'javadoc'),
+}
+
 
 # -- Options for intersphinx -------------------------------------------------
 

src/doc/development/benchmarking.md

+# Benchmarking CaosDB #
+
+Please refer to the file `doc/devel/Benchmarking.md` in the CaosDB sources for developer resources
+how to do benchmarking and profiling of CaosDB.

src/doc/development/structure.rst

-CaosDB's internal structure
+CaosDB's Internal Structure
 ===========================
 
+The CaosDB server
+
+- builds upon the `Restlet <https://restlet.talend.com/>`_ framework to provide a REST interface to
+  the network.  See the :ref:`HTTP Resources` section for more information.
+- uses an SQL database (MariaDB or MySQL) as the backend for data storage.  This is documented in
+  the :ref:`MySQL Backend` section.
+- has an internal scheduling framework to organize the required backend jobs.  Read more on this in
+  the :ref:`Transactions and Schedules<transactions>` section.
+- may use a number of authentication providers. Documentation for this is still to come.
+
+.. _HTTP Resources:
+
+HTTP Resources
+--------------
+
+HTTP resources are implemented in the :java:ref:`resource<org.caosdb.server.resource>` package, in
+classes inheriting from :java:ref:`AbstractCaosDBServerResource` (which inherits Restlet's
+:java:ref:`Resource<org.restlet.resource.Resource>` class).  The main :java:ref:`CaosDBServer` class
+defines which HTTP resource (for example ``/Entity/{specifier}``) will be handled by which class
+(:java:ref:`EntityResource` in this case).
+
+Implementing classes need to overwrite for example the ``httpGetInChildClass()`` method (or methods
+corresponding to other HTTP request methods such as POST, PUT, ...).  Typically, they might call the
+``execute()`` method of a :java:ref:`Transaction<org.caosdb.server.transaction.Transaction>` object.
+Transactions are explained in detail in the :ref:`Transactions and Schedules<transactions>` section.
+
+.. uml::
+
+  @startuml
+  abstract AbstractCaosDBServerResource
+  class RetrieveEntityResource
+  class EntityResource
+  AbstractCaosDBServerResource <|-- RetrieveEntityResource
+  RetrieveEntityResource <|-- EntityResource
+  @enduml
+
+.. _MySQL Backend:
+
+MySQL Backend
+-------------
+
+The MySQL backend in CaosDB may be substituted by backends for, but at the time of writing this
+documentation, only MySQL (MariaDB is used for testing) is implemented.  There are the following
+main packages which handle the backend:
+
+:java:ref:`backend.interfaces<interfaces>`
+    Interfaces which backends may implement.  The main method for most interfaces is
+    ``execute(...)`` with arguments depending on the specific interface, and benchmarking methods
+    (``getBenchmark()`` and ``setTransactionBenchmark(b)`` may also be required.
+
+:java:ref:`backend.implementation.MySQL<MySQL>`
+    MySQL implementations of the interfaces.  Typical "simple" implementations create a prepared SQL
+    statement from the arguments to ``execute(...)`` and send it to the SQL server.
+
+:java:ref:`backend.transaction<backend.transaction>` classes
+    Subclasses of the abstract :java:ref:`BackendTransaction` which implement the ``execute()``
+    method.  These classes may use specific backend implementations (like for example the MySQL
+    implementations) to interact with the backend database.
+
+.. _transactions:
+
+Transactions and Schedules
+--------------------------
+
+