F yaml documentation

A draft of a small documentation of the yaml interface in caosdb-advanced-user-tools.

src/doc/yaml_interface.rst

@@ -41,24 +41,24 @@ Let's start with an example taken from https://gitlab.indiscale.com/caosdb/src/c
              description: 'A table document associated with this recording'
 
 
-This example defines 3 RecordTypes:
+This example defines 3 ``RecordType``s:
 
-- A Project with one obligatory property "datatype"
-- A Person with a "firstName" and a "lastName" (as recommended properties)
-- A LabbookEntry with multiple recommended properties of different data types
+- A ``Project`` with one obligatory property ``datatype``
+- A Person with a ``firstName`` and a ``lastName`` (as recommended properties)
+- A ``LabbookEntry`` with multiple recommended properties of different data types
 
-One major advantage of using this interface (in contrast to the standard python interface) is that properties can be defined and added to record types "on-the-fly". E.g. the three lines for "firstName" as sub entries of Person have two effects on CaosDB:
+One major advantage of using this interface (in contrast to the standard python interface) is that properties can be defined and added to record types "on-the-fly". E.g. the three lines for ``firstName`` as sub entries of ``Person`` have two effects on CaosDB:
 
-- A new property with name "firstName", datatype "TEXT" and description 'first name' is inserted (or updated, if already present) into CaosDB.
-- The new property is added as a recommended property to record type Person.
+- A new property with name ``firstName``, datatype ``TEXT`` and description ``first name`` is inserted (or updated, if already present) into CaosDB.
+- The new property is added as a recommended property to record type ``Person``.
 
-Any furhter occurrences of "firstName" in the yaml file will reuse the definition provided for Person.
+Any further occurrences of ``firstName`` in the yaml file will reuse the definition provided for ``Person``.
 
-Note the difference between the three property declarations of LabbookEntry:
+Note the difference between the three property declarations of ``LabbookEntry``:
 
-- "Project": This record type is added directly as a property of LabbookEntry. Therefore it does not specify any further attributes. Compare to the original declaration of record type "Project".
-- "responsible": This defines and adds a property with name "responsible" to LabbookEntry which has a datatype "Person. Person is defined above.
-- "firstName": This defines and adds a property with the standard data type "TEXT" to record type Person.
+- ``Project``: This record type is added directly as a property of ``LabbookEntry``. Therefore it does not specify any further attributes. Compare to the original declaration of record type ``Project``.
+- ``responsible``: This defines and adds a property with name "responsible" to ``LabbookEntry`, which has a datatype ``Person``. ``Person`` is defined above.
+- ``firstName``: This defines and adds a property with the standard data type ``TEXT`` to record type ``Person``.
 
 Datatypes
 ---------
@@ -69,13 +69,13 @@ List attributes are a bit special:
 
 .. code-block:: yaml
 
-  datatype: LIST(DOUBLE)
+  datatype: LIST<DOUBLE>
 
 would declare a list datatype of DOUBLE elements.
 
 .. code-block:: yaml
 
-  datatype: LIST(Project)
+  datatype: LIST<Project>
 
 would declare a list of elements with datatype Project.
 
@@ -84,8 +84,8 @@ Keywords
 --------
 
 - **parent**: Parent of this entity.
-- **importance**: Importance of this entity.
-- **datatype**: The datatpye of this property, e.g. TEXT, INTEGER or Project.
+- **importance**: Importance of this entity. Possible values: "recommended", "obligatory", "suggested"
+- **datatype**: The datatype of this property, e.g. TEXT, INTEGER or Project.
 - **unit**: The unit of the property, e.g. "m/s".
 - **description**: A description for this entity.
 - **recommended_properties**: Add properties to this entity with importance "recommended".
@@ -94,3 +94,24 @@ Keywords
 - **inherit_from_recommended**: Inherit from another entity using the specified importance level including the higher importance level "obligatory". This would add a corresponding parent and add all obligatory and recommended properties from the parent.
 - **inherit_from_suggested including higher importance levels**: Inherit from another entity using the specified importance level. This would add a corresponding parent and add all obligatory, recommended and suggested properties from the parent.
 - **inherit_from_obligatory**: Inherit from another entity using the specified importance level. This would add a corresponding parent and add all obligatory properties from the parent.
+
+Usage
+-----
+
+You can use the yaml parser directly in python as follows:
+
+
+.. code-block:: python
+   
+  from caosadvancedtools.models import parser as parser
+  model = parser.parse_model_from_yaml("model.yml")
+
+
+This creates a DataModel object containing all entities defined in the yaml file.
+
+You can then use the functions from caosadvancedtools.models.data_model.DataModel to synchronize
+the model with a CaosDB instance, e.g.:
+
+.. code-block:: python
+   
+  model.sync_data_model()