DOC: Fix and extend documentation on inheritance

Summary

See #53 (closed). No new code, just docstrings and documentation

Focus

Updated/added the docstrings of the add_parent methods of Entity, Property, and RecordType in caosdb.models. Also updated the section on inheritance in the data-insertion tutorial. If you are content with the docstrings, we can use the one of Entity.add_parent as an example for a docstring with a list of **kwargs, and the one of RecordType.add_parent as an example for linking to other functions, classes, or methods.

Test Environment

Run make doc and check the documentation. You may have to delete the _apidocs directory and re-install this pylib branch beforehand.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related Issues
• Up-to-date CHANGELOG.md
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there spezifications? Are they satisfied?

For further good practices have a look at our review guidelines.

src/caosdb/common/models.py

@@ -431,14 +431,39 @@ class Entity(object):
     def add_parent(self, parent=None, **kwargs):  # @ReservedAssignment
         """Add a parent to this entity.
 
-        The first parameter is meant to identify the parent entity. So the method expects an instance of
-        Entity, an integer or a string here. Even though, by means of the **kwargs parameter you may pass
-        more parameters to this method. Accepted keywords are: id, name, inheritance. Any other keyword is
-        ignored right now but this may change in the future.
-
-        @param parent: An entity, an id or a name.
-        @param **kwargs: Accepted keywords: id, name, inheritance.
-        @raise UserWarning: If neither a 'parent' parameter, nor the 'id', nor 'name' parameter is passed to this method.
+        Parameters
+        ----------
+        parent : Entity or int or str or None
+            The parent entity, either specified by the Entity object
+            itself, or its id or its name. Default is None.
+        **kwargs : dict, optional
+            Additional keyword arguments for specifying the parent by
+            name or id, and for specifying the mode of inheritance.
+
+            id : int
+                Integer id of the parent entity. Ignored if `parent`
+                is not None.
+            name : str
+                Name of the parent entity. Ignored if `parent is not
+                none`.
+            inheritance : str
+                One of ``obligatory``, ``recommended``, ``suggested``, or ``fix``. Specifies the
+                minimum importance which parent properties need to have to be inherited by this
+                entity. If no `inheritance` is given, no properties will be inherited by the child.
+                This parameter is case-insensitive.
+
+                Note that the behaviour is currently not yet specified when assigning parents to
+                Records, it only works for inheritance of RecordTypes (and Properties).
+
+                For more information, it is recommended to look into the
+                :ref:`data insertion tutorial<tutorial-inheritance-properties>`.
+
+        Raises
+        ------
+        UserWarning
+            If neither a `parent` parameter, nor the `id`, nor `name`
+            parameter is passed to this method.
+
         """
         name = (kwargs['name'] if 'name' in kwargs else None)
         pid = (kwargs['id'] if 'id' in kwargs else None)
@@ -1435,6 +1460,23 @@ class Property(Entity):
             property=property, value=value, **copy_kwargs)
 
     def add_parent(self, parent=None, **kwargs):
+        """Add a parent Entity to this Property.
+
+        Parameters
+        ----------
+        parent : Entity or int or str or None, optional
+            The parent entity
+        **kwargs : dict, optional
+            Additional keyword arguments specifying the parent Entity
+            by id or name, and specifying the inheritance level. See
+            :py:meth:`Entity.add_parent` for more information. Note
+            that by default, `inheritance` is set to ``fix``.
+
+        See Also
+        --------
+        Entity.add_parent
+
+        """
         copy_kwargs = kwargs.copy()
 
         if 'inheritance' not in copy_kwargs:
@@ -1513,6 +1555,24 @@ class RecordType(Entity):
                                     **copy_kwargs)
 
     def add_parent(self, parent=None, **kwargs):
+        """Add a parent to this RecordType
+
+        Parameters
+        ----------
+        parent : Entity or int or str or None, optional
+            The parent entity, either specified by the Entity object
+            itself, or its id or its name. Default is None.
+        **kwargs : dict, optional
+            Additional keyword arguments specifying the parent Entity by id or
+            name, and specifying the inheritance level. See
+            :py:meth:`Entity.add_parent` for more information. Note
+            that by default, `inheritance` is set to ``obligatory``.
+
+        See Also
+        --------
+        Entity.add_parent
+
+        """
         copy_kwargs = kwargs.copy()
 
         if 'inheritance' not in copy_kwargs: