From ed0e312674e9fb801a868c1885e207c00bca840b Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Mon, 8 Aug 2022 13:57:00 +0200
Subject: [PATCH] DOC: Some small changes to the YAML documentation.
---
src/doc/index.rst | 5 ++---
src/doc/yaml_interface.rst | 25 +++++++++++++++++--------
2 files changed, 19 insertions(+), 11 deletions(-)
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 9aa04534..5fdb78da 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -13,9 +13,8 @@ This documentation helps you to :doc:`get started<getting_started>`, explains th
Getting started <README_SETUP>
Concepts <concepts>
- tutorials
- Caosdb-Crawler <crawler>
- YAML Interface <yaml_interface>
+ The Caosdb Crawler <crawler>
+ YAML data model specification <yaml_interface>
_apidoc/modules
diff --git a/src/doc/yaml_interface.rst b/src/doc/yaml_interface.rst
index 476e9282..52d33a17 100644
--- a/src/doc/yaml_interface.rst
+++ b/src/doc/yaml_interface.rst
@@ -1,10 +1,14 @@
-YAML-Interface
---------------
-The yaml interface is a module in caosdb-pylib that can be used to create and update
+===============================
+ YAML data model specification
+===============================
+
+The ``caosadvancedtools`` library features the possibility to create and update
CaosDB models using a simplified definition in YAML format.
-Let's start with an example taken from https://gitlab.indiscale.com/caosdb/src/caosdb-advanced-user-tools/-/blob/dev/unittests/model.yml.
+Let's start with an example taken from `model.yml
+<https://gitlab.indiscale.com/caosdb/src/caosdb-advanced-user-tools/-/blob/dev/unittests/model.yml>`__
+in the library sources.
.. code-block:: yaml
@@ -44,7 +48,7 @@ Let's start with an example taken from https://gitlab.indiscale.com/caosdb/src/c
-This example defines 3 ``RecordType``s:
+This example defines 3 ``RecordTypes``:
- A ``Project`` with one obligatory property ``datatype``
- A Person with a ``firstName`` and a ``lastName`` (as recommended properties)
@@ -69,8 +73,10 @@ Note the difference between the three property declarations of ``LabbookEntry``:
If the data model depends on record types or properties which already exist in CaosDB, those can be
added using the ``extern`` keyword: ``extern`` takes a list of previously defined names.
+
+
Datatypes
----------
+=========
You can use any data type understood by CaosDB as datatype attribute in the yaml model.
@@ -90,7 +96,7 @@ would declare a list of elements with datatype Project.
Keywords
---------
+========
- **parent**: Parent of this entity.
- **importance**: Importance of this entity. Possible values: "recommended", "obligatory", "suggested"
@@ -105,7 +111,7 @@ Keywords
- **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:
@@ -124,3 +130,6 @@ the model with a CaosDB instance, e.g.:
.. code-block:: python
model.sync_data_model()
+
+.. LocalWords: yml projectId UID firstName lastName LabbookEntry entryId textElement labbook
+.. LocalWords: associatedFile extern Textfile DataModel
--
GitLab