Clarify docstring and mention subclassing of run method

docs/configuration.rst

@@ -44,12 +44,12 @@ collections_clean
 
 If ``True`` all configured target locations get wiped out at the beginning.
 
-The related driver of the collection decides, if and clean is needed and how it must be performed.
+The related driver of the collection specifies if cleaning is needed and how to perform it.
 
 If you use nested collections, e.g ``_collections/collection_A/collection_B`` the outer clean routine of
 a collection (here ``collection_A``) deletes also the content of other collections (here ``collection_B``).
 
-Can be overwritten for each collection be setting :ref:`collections_clean`.
+This can be overwritten for each collection be configuring :ref:`collections_clean`.
 
 **Default**: ``True``
 
@@ -60,10 +60,11 @@ Can be overwritten for each collection be setting :ref:`collections_clean`.
 collections_final_clean
 -----------------------
 
-If ``True`` all collections start their clean-up routine after a Sphinx build is done.
-Normally It doesn't matter if the build was an success or stopped.
+If this option is set to ``True``, all collections start their clean-up
+routine after a Sphinx build is done.  Normally It doesn't matter if
+the build was a success or failed.
 
-Works similar to :ref:`conf_collections_clean`, but at the end of the build instead before.
+Works similarly to :ref:`conf_collections_clean`, but at the end of the build instead before.
 
 Can be overwritten for each collection be setting :ref:`collections_final_clean`.
 

docs/drivers/index.rst

@@ -3,7 +3,7 @@
 Drivers
 =======
 
-Drivers represents the technical function, which gets configured by the configuration given by a collection.
+Drivers represent the tasks which get configured by a collection's configuration.
 
 Each collection must reference a single driver, which cares about:
 
@@ -19,16 +19,16 @@ Each collection must reference a single driver, which cares about:
 
    *
 
-Own drivers
+Custom drivers
 -----------
 
-You can specify own drivers directly inside your ``conf.py`` file.
+You can create your own drivers directly inside your ``conf.py`` file.
 
-Using own drivers instead of e.g. a pure function call has several advantages:
+Creating your own drivers has several advantages:
 
 * Configuration handling.
 * Correct and easy logging.
-* Executed during correct Sphinx phases.
+* Ensure execution during correct Sphinx phases.
 * Integrated clean-up.
 * Report capabilities.
 
@@ -55,7 +55,7 @@ Using own drivers instead of e.g. a pure function call has several advantages:
         },
     }
 
-If you have created an awesome driver, please consider to provide it to ``Sphinx-Collections`` by creating
+If you have created an awesome driver, please consider contributing it to ``Sphinx-Collections`` by creating
 a PR on our `github project <https://github.com/useblocks/sphinx-collections>`_ .
 This would help our little Sphinx community a lot. Thanks!
 

sphinxcontrib/collections/drivers/__init__.py

@@ -26,11 +26,11 @@ def __init__(self, collection, config=None):
 
     def run(self):
         """
-        Is the main routine for the driver.
+        This is the main routine for the driver.
 
-        Must be implement by the parent driver class.
+        The run method must be implement by the subclassed driver.
         """
-        raise NotImplementedError("run() function must be implemented by driver {} itself.".format(self.name))
+        raise NotImplementedError("run() function must be implemented by the driver {} itself.".format(self.name))
 
     def clean(self):
         """
@@ -53,18 +53,18 @@ def error(self, message, e=None):
         """
         if e is not None and isinstance(e, BaseException):
             if self.config["safe"]:
-                raise ColectionsDriverError("{}{}".format(self._prefix, message)) from e
+                raise CollectionsDriverError("{}{}".format(self._prefix, message)) from e
             self._log.error(("{}{} - {}".format(self._prefix, message, e)))
         else:
             if self.config["safe"]:
-                raise ColectionsDriverError("{}{}".format(self._prefix, message))
+                raise CollectionsDriverError("{}{}".format(self._prefix, message))
             self._log.error(("{}{}".format(self._prefix, message)))
 
     def info(self, message):
         """
         Writes a log message of level INFO.
 
-        Sets collection and driver information as prefix in front of the message
+        Prefixes collection information and driver name in front of the message.
 
         :param message: string
         :return: None
@@ -115,5 +115,5 @@ def get_path(self, path):
         return path
 
 
-class ColectionsDriverError(BaseException):
+class CollectionsDriverError(BaseException):
     pass