From 5b86d55f57664394e9c439ed2f77b8b7aa669c76 Mon Sep 17 00:00:00 2001
From: Daniel Hornung <d.hornung@indiscale.com>
Date: Thu, 3 Jun 2021 15:38:51 +0200
Subject: [PATCH] DOC FIX: Fixing style, syntax and links.
---
src/doc/CaosDB-Query-Language.md | 2 +-
src/doc/Permissions.rst | 3 +-
src/doc/administration/configuration.rst | 15 +++++----
src/doc/administration/maintenance.rst | 32 +++++++++++--------
.../administration/server_side_scripting.rst | 2 +-
src/doc/conf.py | 4 +--
src/doc/index.rst | 4 +--
src/doc/roles.md | 4 +--
src/doc/specification/AbstractProperty.md | 11 +++++--
src/doc/specification/RecordType.md | 2 +-
10 files changed, 47 insertions(+), 32 deletions(-)
diff --git a/src/doc/CaosDB-Query-Language.md b/src/doc/CaosDB-Query-Language.md
index 07fbdbc3..ffa889c6 100644
--- a/src/doc/CaosDB-Query-Language.md
+++ b/src/doc/CaosDB-Query-Language.md
@@ -121,7 +121,7 @@ Examples:
##### `d1>d2`: Transitive, non-symmetric relation.
Semantics depend on the flavors of d1 and d2. If both are...
###### [UTCDateTime](Datatype#datetime)
-* ''True'' iff the time of d1 is after the the time of d2 according to [https://en.wikipedia.org/wiki/Coordinated_Universal_Time](UTC)
+* ''True'' iff the time of d1 is after the the time of d2 according to [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).
* ''False'' otherwise.
###### [SemiCompleteDateTime](Datatype#datetime)
diff --git a/src/doc/Permissions.rst b/src/doc/Permissions.rst
index a5fae0bb..2a1278ec 100644
--- a/src/doc/Permissions.rst
+++ b/src/doc/Permissions.rst
@@ -1,4 +1,5 @@
-#Permissions
+Permissions
+===========
CaosDB has a fine grained role based permission system. Each interaction
with the server is governed by the current rules of the user, by default
diff --git a/src/doc/administration/configuration.rst b/src/doc/administration/configuration.rst
index bbafcf22..196acb34 100644
--- a/src/doc/administration/configuration.rst
+++ b/src/doc/administration/configuration.rst
@@ -19,18 +19,21 @@ In each of these directories, the server looks for the following files:
``server.conf``
General server configuration options. The possible configuration options are documented inside
- the `default file <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/conf/core/server.conf>`_.
+ the `default file
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
``global_entity_permissions.xml``
- :ref:`Permissions <concepts:Permissions>` which are automatically set, based on user roles.
- See the `default file <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/conf/core/global_entity_permissions.xml>`_.
+ :doc:`Permissions<../Permissions>` which are automatically set, based on user roles. See the
+ `default file
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/global_entity_permissions.xml>`__.
``usersources.ini``
This file defines possible sources which are checked when a user tries to authenticate. Each
defined source has a special section, the possible options are defined separately for each user
source. At the moment the best place to look for this specific documentation is at the API
documentation of :java:type:`UserSource` and its implementing classes. The provided `template
- file <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/conf/core/usersources.ini.template>`_
+ file
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/usersources.ini.template>`__
also has some information. The general concept about authentication realms is described in
:java:type:`UserSources`.
@@ -38,13 +41,13 @@ In each of these directories, the server looks for the following files:
Configuration for dispensed authentication tokens, which can be used to authenticate to CaosDB
without the need of a user/password combination. Possible use cases are server-side scripts or
initial setup after the server start. There is more documentation inside the `template file
- <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/conf/core/authtoken.example.yaml>`_.
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/authtoken.example.yaml>`__.
``cache.ccf``
Configuration for the Java Caching System (JCS) which can be used by the server. More
documentation is `upstream
<http://commons.apache.org/proper/commons-jcs/getting_started/intro.html>`_ and inside `the file
- <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/conf/core/cache.ccf>`_.
+ <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/cache.ccf>`_.
``log4j2-default.properties``, ``log4j2-debug.properties``
Configuration for logging, following the standard described by the `log4j library
diff --git a/src/doc/administration/maintenance.rst b/src/doc/administration/maintenance.rst
index 67d8475b..5b9faeb1 100644
--- a/src/doc/administration/maintenance.rst
+++ b/src/doc/administration/maintenance.rst
@@ -21,12 +21,17 @@ The command could look like::
tar czvf /path/to/new/backup /path/to/caosdb/filesystem.tar.gz
-You can also save the content of CaosDB using XML. This is **not recommended** since it is less reliable than a real SQL backup. However there may be cases in which an XML backup is desirable, e.g., when transferring entities between two different CaosDB instances.
-Collect the entities that you want to export in a :any:`caosdb-pylib:caosdb.common.models.Container`, here
-named ``cont``. Then you can export the XML with::
+You can also save the content of CaosDB using XML. This is **not recommended** since it produces
+less reproducible results than a plain SQL backup. However there may be cases in which an XML backup
+is necessary, e.g., when transferring entities between two different CaosDB instances.
+
+Collect the entities that you want to export in a
+:any:`Container<caosdb-pylib:caosdb.common.models.Container>`, named ``cont`` here. Then you can
+export the XML with::
from caosadvancedtools.export_related import invert_ids
from lxml import etree
+
invert_ids(cont)
xml = etree.tounicode(cont.to_xml(
local_serialization=True), pretty_print=True)
@@ -38,11 +43,11 @@ named ``cont``. Then you can export the XML with::
Restoring a Backup
------------------
-.. note :
+.. warning::
CaosDB should be offline before restoring data.
If you want to restore the internal file system, simply replace it. E.g. if your
-Backup is a tarball::
+backup is a tarball::
tar xvf /path/to/caosroot.tar.gz
@@ -52,16 +57,17 @@ You find the documentation on how to restore the data in the SQL-Backend :any:`
If you want to restore the entities exported to XML, you can do::
- cont = db.Container()
- with open("caosdb_data.xml") as fi:
- cont = cont.from_xml(fi.read())
+ cont = db.Container()
+ with open("caosdb_data.xml") as fi:
+ cont = cont.from_xml(fi.read())
cont.insert()
-
+
User Management
---------------
-The configuration of authentication mechanisms is done via the
-``usersources.ini`` file (see :any:`configuration`).
-We recommend the Python tools (:any:`caosdb-pylib:Administration`) for further administrative tasks (e.g. setting
-user passwords).
+The configuration of authentication mechanisms is done via the ``usersources.ini`` file (see
+:any:`configuration`).
+
+We recommend the Python tools (:any:`caosdb-pylib:administration`) for further administrative tasks
+(e.g. setting user passwords).
diff --git a/src/doc/administration/server_side_scripting.rst b/src/doc/administration/server_side_scripting.rst
index 1f2b9a1d..6dc08999 100644
--- a/src/doc/administration/server_side_scripting.rst
+++ b/src/doc/administration/server_side_scripting.rst
@@ -31,7 +31,7 @@ The script has to be executable and must be placed somewhere in one of the direc
Users will need the ``SCRIPTING:EXECUTE:path:to:the:script`` permission. Here the path to the script is of course relativet to the ``SERVER_SIDE_SCRIPTING_BIN_DIRS`` where it is located.
-For more information see the :doc:`specification of the API <../specs/Server-side-scripting>`
+For more information see the :doc:`specification of the API <../specification/Server-side-scripting>`
Environment
------------
diff --git a/src/doc/conf.py b/src/doc/conf.py
index 119f966e..46580733 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -201,8 +201,8 @@ javadoc_url_map = {
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping
intersphinx_mapping = {
"python": ("https://docs.python.org/", None),
- "caosdb-pylib": ("https://caosdb.gitlab.io/caosdb-pylib/", None),
- "caosdb-mysqlbackend": ("https://caosdb.gitlab.io/caosdb-mysqlbackend/", None),
+ "caosdb-pylib": ("https://docs.indiscale.com/caosdb-pylib/", None),
+ "caosdb-mysqlbackend": ("https://docs.indiscale.com/caosdb-mysqlbackend/", None),
}
diff --git a/src/doc/index.rst b/src/doc/index.rst
index 8c366b3c..2ae00f7e 100644
--- a/src/doc/index.rst
+++ b/src/doc/index.rst
@@ -19,8 +19,8 @@ Welcome to caosdb-server's documentation!
Welcome to the CaosDB, the flexible semantic data management toolkit!
-This documentation helps you to :doc:`get started<getting_started>`, explains the most important
-:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials>`.
+This documentation helps you to :doc:`get started<README_SETUP>`, explains the most important
+:doc:`concepts<concepts>` and has information if you want to :doc:`develop<development/devel>` CaosDB yourself.
Indices and tables
diff --git a/src/doc/roles.md b/src/doc/roles.md
index b70f5450..5f4641b7 100644
--- a/src/doc/roles.md
+++ b/src/doc/roles.md
@@ -10,7 +10,7 @@ users may have the same role, and there may be roles without any users.
The user and their roles are always returned by the server in answers to requests
and can thus be interpreted and used by clients. The most important use though
-is [permission](permissions) checking in the server: Access and
+is [permission](Permissions) checking in the server: Access and
modification of
entities can be controlled via roles, so that users of a given role are allowed
or denied certain actions. Incidentally, the permission to edit the permissions
@@ -32,4 +32,4 @@ There are some special roles, which are automatically assigned to users:
Except for the `anonymous` role, these special roles are not returned by the
server, but can nevertheless be used to define
-[permissions](permissions.rst).
+[permissions](Permissions).
diff --git a/src/doc/specification/AbstractProperty.md b/src/doc/specification/AbstractProperty.md
index d594f819..a337fa5e 100644
--- a/src/doc/specification/AbstractProperty.md
+++ b/src/doc/specification/AbstractProperty.md
@@ -1,7 +1,12 @@
+.. note ::
+
+ This document has not been updated for a long time. Although it is concerned with the mostly
+ stable API, its content may no longer reflect the actual CaosDB behavior.
+
# AbstractProperty Specification
## Introduction
-An `AbstractProperty` is one of the basal [objects of HeartDB](./HeartDBObject).
+An `AbstractProperty` is one of the basal objects of HeartDB.
An `AbstractProperty` MUST have the following _qualities_ (shortcut in brackets):
* a persistent id (`id`)
* an unique name (`name`)
@@ -54,7 +59,7 @@ Any xml representation of an `AbstractProperty` that is retrieved from the Heart
<Property id="$id" name="$name" description="$description" generator="$generator" creator="$creator" created="$created" type="file" />
'''General Notes:
-* If the called Property does not exist or if the Property called without permission, the HeartDB Server will return an [Error](./Errorcodes).
+* If the called Property does not exist or if the Property called without permission, the HeartDB Server will return an Error.
### POST AbstractProperty
Any xml representation of an `AbstractProperty` that is to be posted to the HeartDB server MUST have exactly ONE of the following forms, depending on the `AbstractProperty's` type:
@@ -80,7 +85,7 @@ Any xml representation of an `AbstractProperty` that is to be posted to the Hear
* The `AbstractProperty's` `id` and timestamp (`created`) will be generated by the HeartDB Server.
* The `AbstractProperty's` creator will be determined by the HeartDB Server depending on it's policy configuration.
* Any given attribute beyond these will be *ignored*.
-* If the `<Property/>` tag isn't compliant with these the HeartDB Server will return an [Error](./Errorcodes).
+* If the `<Property/>` tag isn't compliant with these the HeartDB Server will return an Error.
----
## Examples
diff --git a/src/doc/specification/RecordType.md b/src/doc/specification/RecordType.md
index 068c433d..a7830b86 100644
--- a/src/doc/specification/RecordType.md
+++ b/src/doc/specification/RecordType.md
@@ -1,5 +1,5 @@
# RecordType
-----
+
## Overview
RecordTypes function as templates for [[Record|Records]], they provide a description for a type of Record and define which [[Property|Properties]] should be present. Properties come with an _importance_ attribute which tells the user or client program how strongly necessary the Property is. (As all other entities,) RecordTypes can be inherited from other RecordTypes (or any Entities). When RecordTypes inherit from other RecordTypes, the _inheritance_ flag tells which properties shall be inherited.
--
GitLab