From f90b4a74bf7ffd0090f5764a74aa289e2804b153 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrik=20tom=20W=C3=B6rden?= <h.tomwoerden@indiscale.com>
Date: Sun, 13 Nov 2022 19:10:52 +0100
Subject: [PATCH] DOC: enhance docs
---
src/doc/concepts.rst | 24 +++++++++++++++++++++++-
src/doc/index.rst | 14 +++++++-------
2 files changed, 30 insertions(+), 8 deletions(-)
diff --git a/src/doc/concepts.rst b/src/doc/concepts.rst
index c0f21cba..bbaf8618 100644
--- a/src/doc/concepts.rst
+++ b/src/doc/concepts.rst
@@ -34,8 +34,30 @@ src/converters.py
Identifiables
+++++++++++++
+An Identifiable of a Record is like the fingerprint of a Record.
+
+The identifiable contains the information that is used by the CaosDB Crawler to identify Records.
+In order to check whether a Record exits in the CaosDB Server, the CaosDB Crawler creates a query
+using the information contained in the Identifiable.
+
+For example, suppose a certain experiment is at most done once per day, then the identifiable could
+consist of the RecordType "SomeExperiment" and the Property "date".
+
+You can think of the properties that are used by the identifiable as dictionary. For each property
+name there can be one value. However, this value can be a list such that the created query can look
+like "FIND RECORD ParamenterSet WITH a=5 AND a=6". This is meaningful if there is a ParamenterSet
+with two Properties with the name 'a' or if 'a' is a list containing at least the values 5 and 6.
+
+The path of a File object can serve as a Property that identifies files and similarly the name of
+Records can be used.
+
+An identifiable can only use one RecordType eventhough the identified Records might have multiple
+Parents.
+
Relevant sources in:
-src/identifiable_adapters.py
+
+- src/identifiable_adapters.py
+- src/identifiable.py
The Crawler
+++++++++++
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 724bcc54..3f55ae51 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -1,5 +1,5 @@
-Crawler 2.0 Documentation
-=========================
+CaosDB-Crawler Documentation
+============================
.. toctree::
@@ -17,18 +17,18 @@ Crawler 2.0 Documentation
-This is the documentation for the crawler (previously known as crawler 2.0) for CaosDB, ``caosdb-crawler``.
+This is the documentation for CaosDB-Crawler (previously known as crawler 2.0)
+the main tool for automatic data insertion into CaosDB.
-The crawler is the main date integration tool for CaosDB.
Its task is to automatically synchronize data found on file systems or in other
sources of data with the semantic data model of CaosDB.
More specifically, data that is contained in a hierarchical structure is converted to a data
structure that is consistent with a predefined semantic data model.
-The hierarchical sturcture can be for example a file tree. However it can be
-also something different like the contents of a json file or a file tree with
-json files.
+The hierarchical structure can be for example a file tree. However it can be
+also something different like the contents of a JSON file or a file tree with
+JSON files.
This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important
:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials/index>`.
--
GitLab