DOC STY: Formatting of docstrings.

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)

src/caosadvancedtools/models/__init__.py

+"""Submodule for working with data models.
+"""

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
         -------

src/caosadvancedtools/models/parser.py

 """
-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),

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,