From 73d2ad79726adfc929fa35c5f3ddb8ddffd653da Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Thu, 13 Apr 2023 14:13:58 +0200
Subject: [PATCH] DOC: Some formatting to appease the sphinx.
---
src/caosdb/apiutils.py | 10 ++++-----
src/caosdb/common/administration.py | 2 +-
src/caosdb/common/models.py | 17 ++++++++-------
src/caosdb/connection/utils.py | 7 ++++--
src/caosdb/utils/create_revision.py | 34 ++++++++++++++++-------------
src/doc/conf.py | 3 +++
src/doc/tutorials/first_steps.rst | 3 ++-
7 files changed, 44 insertions(+), 32 deletions(-)
diff --git a/src/caosdb/apiutils.py b/src/caosdb/apiutils.py
index 9c68e9db..a5a936c5 100644
--- a/src/caosdb/apiutils.py
+++ b/src/caosdb/apiutils.py
@@ -22,9 +22,8 @@
#
# ** end header
#
-"""API-Utils:
+"""API-Utils: Some simplified functions for generation of records etc.
-Some simplified functions for generation of records etc.
"""
import logging
@@ -206,9 +205,10 @@ def compare_entities(old_entity: Entity, new_entity: Entity, compare_referenced_
- Additional parents (a list under key "parents")
- Information about properties:
- Each property lists either an additional property or a property with a changed:
- - ... datatype
- - ... importance or
- - ... value (not implemented yet)
+ - datatype
+ - importance or
+ - value (not implemented yet)
+
In case of changed information the value listed under the respective key shows the
value that is stored in the respective entity.
diff --git a/src/caosdb/common/administration.py b/src/caosdb/common/administration.py
index bd09c626..a27aaf04 100644
--- a/src/caosdb/common/administration.py
+++ b/src/caosdb/common/administration.py
@@ -385,7 +385,7 @@ action : str
Either "grant" or "deny"
permission : str
- For example "RETRIEVE:*".
+ For example ``RETRIEVE:*``.
priority : bool, optional
Whether the priority shall be set, defaults is False.
diff --git a/src/caosdb/common/models.py b/src/caosdb/common/models.py
index a95ff637..9ba54c49 100644
--- a/src/caosdb/common/models.py
+++ b/src/caosdb/common/models.py
@@ -33,6 +33,7 @@ transactions.
All additional classes are either important for the entities or the
transactions.
"""
+
from __future__ import print_function, unicode_literals
from __future__ import annotations # Can be removed with 3.10.
@@ -1372,15 +1373,15 @@ out: List[Entity]
unique=True, flags=None, sync=True):
"""Update this entity.
- There are two possible work-flows to perform this update:
- First:
- 1) retrieve an entity
- 2) do changes
- 3) call update method
+There are two possible work-flows to perform this update:
+First:
+ 1) retrieve an entity
+ 2) do changes
+ 3) call update method
- Second:
- 1) construct entity with id
- 2) call update method.
+Second:
+ 1) construct entity with id
+ 2) call update method.
For slight changes the second one it is more comfortable. Furthermore, it is possible to stay
off-line until calling the update method. The name, description, unit, datatype, path,
diff --git a/src/caosdb/connection/utils.py b/src/caosdb/connection/utils.py
index 9056bf9d..095d4703 100644
--- a/src/caosdb/connection/utils.py
+++ b/src/caosdb/connection/utils.py
@@ -45,13 +45,16 @@ def urlencode(query):
3) All other parameters which can be passed to the respective functions are
not implemented here and the default parameters will be used.
+
+.. code::
+
>>> urlencode({'key': ['val1', 'val2']}, doseq=True)
Traceback (most recent call last):
...
TypeError: urlencode() got an unexpected keyword argument 'doseq'
- Otherwise, this functions works exactly as its counterparts in the urllib
- modules when they are called with only the query parameter.
+Otherwise, this functions works exactly as its counterparts in the urllib
+modules when they are called with only the query parameter.
Parameters
----------
diff --git a/src/caosdb/utils/create_revision.py b/src/caosdb/utils/create_revision.py
index 0b7ce996..419e1c9f 100644
--- a/src/caosdb/utils/create_revision.py
+++ b/src/caosdb/utils/create_revision.py
@@ -34,13 +34,15 @@ def bend_references(from_id, to_id, except_for=None):
and those references are changed to point to to_id.
entities having an id listed in except_for are excluded.
- params:
- from_id : int
- the old object to which references where pointing
- to_id : int
- the new object to which references will be pointing
- except_for : list of int
- entities with id of this list will not be changed
+Parameters
+----------
+
+from_id : int
+ the old object to which references where pointing
+to_id : int
+ the new object to which references will be pointing
+except_for : list of int
+ entities with id of this list will not be changed
"""
if except_for is None:
except_for = [to_id]
@@ -71,14 +73,16 @@ def create_revision(old_id, prop, value):
This function changes the record with id old_id. The value of the
propertye prop is changed to value.
- params:
- old_id : int
- id of the record to be changed
- prop : string
- name of the property to be changed
- value : type of corresponding property
- the new value of the corresponding property
- """
+Parameters
+----------
+
+old_id : int
+ id of the record to be changed
+prop : string
+ name of the property to be changed
+value : type of corresponding property
+ the new value of the corresponding property
+"""
record = db.execute_query("FIND {}".format(old_id))[0]
new_rec = record.copy()
new_rec.get_property(prop).value = value
diff --git a/src/doc/conf.py b/src/doc/conf.py
index 5632fd79..819ef61d 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -78,6 +78,9 @@ exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
+suppress_warnings = [
+ "autosectionlabel.*", # duplicate labels
+]
# -- Options for HTML output -------------------------------------------------
diff --git a/src/doc/tutorials/first_steps.rst b/src/doc/tutorials/first_steps.rst
index 7366d391..c84ec52a 100644
--- a/src/doc/tutorials/first_steps.rst
+++ b/src/doc/tutorials/first_steps.rst
@@ -52,6 +52,7 @@ Let's look at the first element:
<Record ...
.. The above example needs doctest ELLIPSIS
+
You see that the object is a Record. It has a Parent and two Properties.
.. note::
@@ -119,7 +120,7 @@ If the files are large data files, it is often a better idea to only retrieve th
Summary
-------
-Now you know, how you can use Python to send queries to CaosDB and you can access
+Now you know how to use Python to send queries to CaosDB and you can access
the result Records and their properties.
The next tutorial shows how to make some meaningful use of this.
--
GitLab