From 36a81616f1c71680f52c6f56812a1c4a5accafbb Mon Sep 17 00:00:00 2001
From: Daniel Hornung <d.hornung@indiscale.com>
Date: Wed, 12 May 2021 11:27:21 +0200
Subject: [PATCH] DOC STY: Formatting of docstrings.
---
src/caosadvancedtools/cache.py | 11 ++++++----
src/caosadvancedtools/models/__init__.py | 2 ++
src/caosadvancedtools/models/data_model.py | 8 +++----
src/caosadvancedtools/models/parser.py | 25 +++++++++++-----------
src/doc/conf.py | 13 +++++++----
5 files changed, 34 insertions(+), 25 deletions(-)
diff --git a/src/caosadvancedtools/cache.py b/src/caosadvancedtools/cache.py
index c255a00d..3dac86ec 100644
--- a/src/caosadvancedtools/cache.py
+++ b/src/caosadvancedtools/cache.py
@@ -171,13 +171,16 @@ class UpdateCache(Cache):
return old_ones
def insert(self, cont, run_id):
- """ insert a pending, unauthorized update
+ """Insert a pending, unauthorized update
- Parameters:
- -----------
+
+ Parameters
+ ----------
cont: Container with the records to be updated containing the desired
version, i.e. the state after the update.
- run_id: the id of the crawler run
+
+ run_id: int
+ The id of the crawler run
"""
cont = put_in_container(cont)
old_ones = UpdateCache.get_previous_version(cont)
diff --git a/src/caosadvancedtools/models/__init__.py b/src/caosadvancedtools/models/__init__.py
index e69de29b..d70cb810 100644
--- a/src/caosadvancedtools/models/__init__.py
+++ b/src/caosadvancedtools/models/__init__.py
@@ -0,0 +1,2 @@
+"""Submodule for working with data models.
+"""
diff --git a/src/caosadvancedtools/models/data_model.py b/src/caosadvancedtools/models/data_model.py
index f4fd7c7e..a4804dd0 100644
--- a/src/caosadvancedtools/models/data_model.py
+++ b/src/caosadvancedtools/models/data_model.py
@@ -106,7 +106,7 @@ class DataModel(dict):
print(ent.name)
if noquestion or str(input("Do you really want to insert those "
- "entities? [y] ")).lower() == "y":
+ "entities? [y/N] ")).lower() == "y":
non_existing_entities.insert()
self.sync_ids_by_name(non_existing_entities)
print("Updated entities.")
@@ -131,7 +131,7 @@ class DataModel(dict):
if any_change:
if noquestion or input("Do you really want to apply the above "
- "changes? [y]") == "y":
+ "changes? [y/N]") == "y":
existing_entities.update()
print("Synchronized existing entities.")
else:
@@ -171,9 +171,7 @@ class DataModel(dict):
A iterable with entities.
names : iterable of str
Only entities which do *not* have one of these names will end up in
- the
-
- returned iterable.
+ the returned iterable.
Returns
-------
diff --git a/src/caosadvancedtools/models/parser.py b/src/caosadvancedtools/models/parser.py
index 96cbb89c..5e1532e0 100644
--- a/src/caosadvancedtools/models/parser.py
+++ b/src/caosadvancedtools/models/parser.py
@@ -1,5 +1,5 @@
"""
-This script provides methods to read a DataModel from a yaml file.
+This module (and script) provides methods to read a DataModel from a YAML file.
If a file name is passed to parse_model_from_yaml it is parsed and a DataModel
is created. The yaml file needs to be structured in a certain way which will be
@@ -13,7 +13,7 @@ and will be added with the respective importance. These properties can be
RecordTypes or Properties and can be defined right there.
Every Property or RecordType only needs to be defined once anywhere. When it is
not defined, simply the name can be supplied with no value.
-Parents can be provided under the inherit_from_xxxx keywords. The value needs
+Parents can be provided under the 'inherit_from_xxxx' keywords. The value needs
to be a list with the names. Here, NO NEW entities can be defined.
"""
import re
@@ -24,9 +24,10 @@ import yaml
from .data_model import DataModel
+# Keywords which are allowed in data model descriptions.
KEYWORDS = ["parent",
"importance",
- "datatype",
+ "datatype", # for example TEXT, INTEGER or REFERENCE
"unit",
"description",
"recommended_properties",
@@ -95,12 +96,12 @@ class Parser(object):
Parameters
----------
filename : str
- The path to the YAML file.
+ The path to the YAML file.
Returns
-------
out : DataModel
- The created DataModel
+ The created DataModel
"""
with open(filename, 'r') as outfile:
ymlmodel = yaml.load(outfile, Loader=SafeLineLoader)
@@ -112,12 +113,12 @@ class Parser(object):
Parameters
----------
string : str
- The YAML string.
+ The YAML string.
Returns
-------
out : DataModel
- The created DataModel
+ The created DataModel
"""
ymlmodel = yaml.load(string, Loader=SafeLineLoader)
return self._create_model_from_dict(ymlmodel)
@@ -128,12 +129,12 @@ class Parser(object):
Parameters
----------
ymlmodel : dict
- The dictionary parsed from a YAML file.
+ The dictionary parsed from a YAML file.
Returns
-------
out : DataModel
- The created DataModel
+ The created DataModel
"""
if not isinstance(ymlmodel, dict):
@@ -185,15 +186,15 @@ class Parser(object):
Parameters
----------
name :
- The value to be converted to a string.
+ The value to be converted to a string.
context : obj
- Will be printed in the case of warnings.
+ Will be printed in the case of warnings.
Returns
-------
out : str
- If `name` was a string, return it. Else return str(`name`).
+ If `name` was a string, return it. Else return str(`name`).
"""
if name is None:
print("WARNING: Name of this context is None: {}".format(context),
diff --git a/src/doc/conf.py b/src/doc/conf.py
index 29b790d4..fef2ee67 100644
--- a/src/doc/conf.py
+++ b/src/doc/conf.py
@@ -17,12 +17,13 @@
# sys.path.insert(0, os.path.abspath('../caosdb'))
-# -- Project information -----------------------------------------------------
-
import sphinx_rtd_theme
+
+# -- Project information -----------------------------------------------------
+
project = 'caosadvancedtools'
-copyright = '2020, IndiScale GmbH'
+copyright = '2021, IndiScale GmbH'
author = 'Daniel Hornung'
# The short X.Y version
@@ -92,6 +93,9 @@ html_theme = "sphinx_rtd_theme"
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
+# Disable static path to remove warning.
+html_static_path = []
+
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
@@ -185,10 +189,11 @@ epub_exclude_files = ['search.html']
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
- 'https://docs.python.org/': None,
+ "python": ("https://docs.python.org/", None),
"caosdb-pylib": ("https://caosdb.gitlab.io/caosdb-pylib/", None),
}
+
# TODO Which options do we want?
autodoc_default_options = {
'members': None,
--
GitLab