diff --git a/docs/configuration.rst b/docs/configuration.rst index e379152..f18571d 100644 --- a/docs/configuration.rst +++ b/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`. diff --git a/docs/drivers/index.rst b/docs/drivers/index.rst index 6ba5bfb..b250362 100644 --- a/docs/drivers/index.rst +++ b/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 `_ . This would help our little Sphinx community a lot. Thanks! diff --git a/sphinxcontrib/collections/drivers/__init__.py b/sphinxcontrib/collections/drivers/__init__.py index d44aa33..c7473d5 100644 --- a/sphinxcontrib/collections/drivers/__init__.py +++ b/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