Improve documentation (#6)

Author: adrien-berchet

README.md

@@ -47,12 +47,12 @@ If one wants to compare two directories with the following structures:
 ```
 
 ```bash
-    └── compared_dir
-        ├── sub_dir_1
-        |   ├── sub_file_1.a
-        |   └── sub_file_2.b
-        |   └── sub_file_3.b
-        └── file_1.c
+└── compared_dir
+    ├── sub_dir_1
+    |   ├── sub_file_1.a
+    |   └── sub_file_2.b
+    |   └── sub_file_3.b
+    └── file_1.c
 ```
 
 These two directories can be compared with the following code:
@@ -124,6 +124,34 @@ Changed the value of '[a]' from 1 to 2.
 Changed the value of '[b][0]' from 1 to 10.
 ```
 
+Finally, the comparators have parameters that can be passed either to be used for all files of a
+given extension or only for a specific file:
+
+```python
+import dir_content_diff
+
+# Get the default comparators
+comparators = dir_content_diff.get_comparators()
+
+# Replace the comparators for JSON files to perform the comparison with a given tolerance
+comparators[".json"] = dir_content_diff.JsonComparator(default_diff_kwargs={"tolerance": 0.1})
+
+# Use a specific tolerance for the file ``sub_dir_1/sub_file_1.a``
+# In this case, the kwargs are used to compute the difference by default, except the following
+# specific kwargs: ``return_raw_diffs``, ``load_kwargs``, ``format_data_kwargs``, ``filter_kwargs``,
+# ``format_diff_kwargs``, ``sort_kwargs``, ``concat_kwargs`` and ``report_kwargs``.
+specific_args = {"sub_dir_1/sub_file_1.a": {"tolerance": 0.5}}
+
+dir_content_diff.assert_equal_trees(
+    "reference_dir",
+    "compared_dir",
+    comparators=comparators,
+    specific_args=specific_args,
+)
+```
+
+Each comparator has different arguments that are detailed in the documentation.
+
 
 ### Export formatted data
 

dir_content_diff/base_comparators.py

@@ -321,8 +321,16 @@ def _format_change_value(value):
     def diff(self, ref, comp, *args, **kwargs):
         """Compare 2 dictionnaries.
 
-        This function calls :func:`dictdiffer.diff`, read the doc of this function for details on
-        args and kwargs.
+        This function calls :func:`dictdiffer.diff` to compare the dictionaries, read the doc of
+        this function for details on args and kwargs.
+
+        Keyword Args:
+            tolerance: Relative threshold to consider when comparing two float numbers.
+            absolute_tolerance: Absolute threshold to consider when comparing
+                two float numbers.
+            ignore: Set of keys that should not be checked.
+            path_limit: List of path limit tuples or :class:`dictdiffer.utils.Pathlimit`
+                object to limit the diff recursion depth.
         """
         if len(args) > 5:
             dot_notation = args[5]
@@ -342,7 +350,10 @@ def format_diff(self, difference):
 
 
 class JsonComparator(DictComparator):
-    """Comparator for JSON files."""
+    """Comparator for JSON files.
+
+    This comparator is based on the :class:`DictComparator` and uses the same parameters.
+    """
 
     def load(self, path):
         """Open a JSON file."""
@@ -352,7 +363,10 @@ def load(self, path):
 
 
 class YamlComparator(DictComparator):
-    """Comparator for YAML files."""
+    """Comparator for YAML files.
+
+    This comparator is based on the :class:`DictComparator` and uses the same parameters.
+    """
 
     def load(self, path):
         """Open a YAML file."""
@@ -364,6 +378,8 @@ def load(self, path):
 class XmlComparator(DictComparator):
     """Comparator for XML files.
 
+    This comparator is based on the :class:`DictComparator` and uses the same parameters.
+
     .. warning:: The XML files must have only one root.
 
     .. note::
@@ -447,13 +463,26 @@ def xmltodict(obj):
 
 
 class PdfComparator(BaseComparator):
-    """Compartor for PDF files."""
+    """Comparator for PDF files."""
 
     def diff(self, ref, comp, *args, **kwargs):
         """Compare data from two PDF files.
 
         This function calls the `diff_pdf_visually.pdfdiff() <https://github.com/bgeron/diff-pdf-
         visually/blob/21e85f1db1bdaee5c0e8e0b730771d6c4e8c3e44/diff_pdf_visually/diff.py#L83>`_
         function, read the doc of this function for details on args and kwargs.
+        It compares the visual aspects of the PDF files, ignoring the invisible content (e.g. file
+        header or invisible things like white font on white background). The PDF files are converted
+        into images using ``ImageMagick`` and then these images are compared.
+
+        Keyword Args:
+            threshold (int): The threshold used to compare the images.
+            tempdir (pathlib.Path): Empty directory where the temporary images will be exported.
+            dpi (int): The resolution used to convert the PDF files into images.
+            verbosity (int): The log verbosity.
+            max_report_pagenos (int): Only this number of the different pages will be logged (only
+                used if the verbosity is greater than 1).
+            num_threads (int): If set to 2 (the default), the image conversion are processed in
+                parallel. If set to 1 it is processed sequentially.
         """
         return not pdfdiff(ref, comp, *args, **kwargs)