Extend documentation of FileFinder and FileContainer (#141)

* extend documentation of FileFinder and FileContainer

* add meta, paths and items to api.rst

* CHANGELOG

* run velin

CHANGELOG.md

@@ -2,8 +2,7 @@
 
 ## v0.4.0 - unreleased
 - Added documentation files for readthedocs ([#134](https://github.com/mpytools/filefisher/pull/134))
-  and extended the documentation with usage ([#135](https://github.com/mpytools/filefisher/pull/135)),
-  and installation instructions ([#136](https://github.com/mpytools/filefisher/pull/136))
+  and extended the documentation with usage ([#135](https://github.com/mpytools/filefisher/pull/135)), installation instructions ([#136](https://github.com/mpytools/filefisher/pull/136)), as well as extension of the api documentation ([#141](https://github.com/mpytools/filefisher/pull/141))
 - Added two methods to find _exactly_ one file or path (and raise an error otherwise):
   `FileFinder.find_single_file` and `FileFinder.find_single_path`
   ([#101](https://github.com/mpytools/filefisher/pull/101)).

docs/source/api.rst

@@ -29,6 +29,9 @@ FileContainer
    :toctree: generated/
 
    ~FileContainer
+   ~FileContainer.meta
+   ~FileContainer.paths
+   ~FileContainer.items
    ~FileContainer.search
    ~FileContainer.concat
 

filefisher/_filefinder.py

@@ -534,7 +534,8 @@ def find_single_path(self, keys=None, **keys_kwargs) -> "FileContainer":
 
         Raises
         ------
-        ValueError : if more or less than one path is found
+        ValueError
+            if more or less than one path is found.
         """
 
         return self.path.find_single(keys, **keys_kwargs)
@@ -557,7 +558,8 @@ def find_single_file(self, keys=None, **keys_kwargs) -> "FileContainer":
 
         Raises
         ------
-        ValueError : if more or less than one file is found
+        ValueError
+            if more or less than one file is found.
         """
 
         return self.full.find_single(keys, **keys_kwargs)
@@ -585,14 +587,6 @@ def __init__(self, df: pd.DataFrame):
         ----------
         df : pd.DataFrame
             DataFrame with info about found paths from FileFinder.
-
-        Properties
-        ----------
-        meta : list[dict[str, Any]]
-            List of metadata dictionaries.
-        paths : list[str]
-            List of paths.
-            
         """
 
         self.df = df
@@ -623,17 +617,35 @@ def __getitem__(self, key):
 
     @property
     def meta(self) -> list[dict[str, Any]]:
+        """Return metadata as list of dictionaries"""
         return self.df.to_dict("records")
 
     @property
     def paths(self) -> list[str]:
+        """Return paths as list"""
         return self.df.index.to_list()
 
     def items(self) -> Generator[tuple[str, dict[str, Any]], None, None]:
+        """Return a generator of (path, metadata) tuples"""
         for index, element in self.df.iterrows():
             yield index, element.to_dict()
 
     def combine_by_key(self, keys=None, sep="."):
+        """combine columns
+
+        Parameters
+        ----------
+        keys : list[str], optional
+            List of keys to combine. If None, all keys are combined.
+        sep : str, default "."
+            Separator between the keys.
+
+        Returns
+        -------
+        pd.Series
+            pd.Series with combined columns where the keys are seperated by `sep`.
+
+        """
         warnings.warn(
             "`combine_by_key` has been deprecated and will be removed in a future version",
             FutureWarning,
@@ -642,7 +654,21 @@ def combine_by_key(self, keys=None, sep="."):
         return self._combine_by_keys(keys=keys, sep=sep)
 
     def _combine_by_keys(self, keys=None, sep="."):
-        """combine columns"""
+        """combine columns
+
+        Parameters
+        ----------
+        keys : list[str], optional
+            List of keys to combine. If None, all keys are combined.
+        sep : str, default "."
+            Separator between the keys.
+
+        Returns
+        -------
+        pd.Series
+            pd.Series with combined columns where the keys are seperated by `sep`.
+
+        """
 
         if keys is None:
             keys = list(self.df.columns)
@@ -654,7 +680,7 @@ def search(self, **query):
 
         Parameters
         ----------
-        **query: Mapping[str, str | int | list[str | int]]
+        **query : Mapping[str, str | int | list[str | int]]
             Search query.
 
         Notes