docs: add documentation for discover addressbook type

Author: antonmosich

doc/source/examples/khard.conf.example

@@ -8,6 +8,9 @@
 path = ~/.contacts/family/
 [[friends]]
 path = ~/.contacts/friends/
+[[work]]
+path = ~/.work/**/client-*-contacts/
+type = discover
 
 [general]
 debug = no

doc/source/man/khard.conf.rst

@@ -41,8 +41,10 @@ addressbooks
   This section contains several subsections, but at least one. Each subsection
   can have an arbitrary name which will be the name of an addressbook known to
   khard.  Each of these subsections **must** have a *path* key with the path to
-  the folder containing the vCard files for that addressbook.  The *path* value
-  supports environment variables and tilde prefixes.  :program:`khard` expects
+  the folder containing the vCard files for that addressbook. Optionally, you
+  can set the *type* value to either ``discover`` or ``vdir``, the default. The
+  *path* value supports environment variables and tilde prefixes. When using
+  the ``discover`` type, it also supports globbing. :program:`khard` expects
   the vCard files to hold only one VCARD record each and end in a :file:`.vcf`
   extension.
 

khard/config.py

@@ -142,6 +142,15 @@ def _validate(config: configobj.ConfigObj) -> configobj.ConfigObj:
 
     @classmethod
     def _unfold_discover_books(cls, addressbooks: configobj.Section) -> configobj.Section:
+        """Expand globs in path of addressbooks of type "discover"
+
+        This expands all addressbooks of type "discover" into (potentially)
+        multiple addressbooks of type "vdir". The names are automatically generated
+        based on the directory name.
+
+        :param config: the configuration to be changed
+        :returns: the changed configuration with no "discover" addressbooks
+        """
         for section_name, book in addressbooks.copy().items():
             if book["type"] != "discover":
                 continue
@@ -165,6 +174,14 @@ def _unfold_discover_books(cls, addressbooks: configobj.Section) -> configobj.Se
 
     @staticmethod
     def _find_leaf_dirs(hits: Iterable[str]) -> set[str]:
+        """Find leaf directories in a tree of hits when using glob.iglob
+
+        The hits are neither guaranteed to be unique nor leaf directories, both
+        of which are enforced by this function.
+
+        :param hits: the hits of a glob as returned by glob.iglob
+        :returns: a set of path strings
+        """
         dirs = {os.path.normpath(hit) for hit in hits if os.path.isdir(hit)}
         parents = {os.path.normpath(os.path.join(dir, os.pardir)) for dir in dirs}
         return dirs - parents