Adds more drivers

.gitignore

@@ -129,4 +129,6 @@ dmypy.json
 .pyre/
 
 .envrc
-.idea
+.idea
+
+_collections/

docs/conf.py

@@ -28,10 +28,36 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
     'sphinxcontrib.collections'
 ]
 
+
+def my_func(config):
+    string = 'This data gets written into {}'.format(config['target'])
+    return string
+
+
+from sphinxcontrib.collections.drivers import Driver
+from sphinxcontrib.collections.api import register_driver
+
+
+class myDriver(Driver):
+    def run(self):
+        self.info('Run for source {}'.format(self.config['source']))
+
+    def clean(self):
+        self.info('Clean')
+
+register_driver('my_driver', myDriver)
+
+
 collections = {
+    'driver_test': {
+        'driver': 'my_driver',
+        'source': '../tests/dummy/',
+        'active': True,
+    },
     'copy_folder_test': {
         'driver': 'copy_folder',
         'source': '../tests/dummy/',
@@ -44,11 +70,28 @@
         'target': 'dummy_new.rst',
         'active': True,
 
+    },
+    'string_test': {
+        'driver': 'string',
+        'source': 'Take **this**!!!',
+        'target': 'dummy_string.rst',
+        'active': True,
+    },
+    'function_test': {
+        'driver': 'function',
+        'source': my_func,
+        'target': 'dummy_function.rst',
+        'active': True,
+    },
+    'report': {
+        'driver': 'report',
+        'target': 'doc_collection_report.rst',
+        'active': True,
     }
 
 }
 
-collections_final_clean = True
+collections_final_clean = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/drivers/copy_folder.rst

@@ -13,3 +13,14 @@ Copies a folder tree from ``source`` into your documentation project::
       }
    }
 
+Options
+-------
+
+ignore
+~~~~~~
+
+List of file matches, which shall get ignored from copy.
+
+This variable is internally given to
+`shutil.ignore_patterns <https://docs.python.org/3/library/shutil.html#shutil.ignore_patterns>`_.
+So it must follow its syntax rules.

docs/drivers/function.rst

@@ -0,0 +1,39 @@
+function
+========
+
+Executes a function referenced by ``source`` and writes its return value into a file specified by ``target``.
+
+.. code-block:: python
+
+    def my_own_data(config):
+        string = 'This data gets written into {}'.format(config['target'])
+
+        return string
+
+    collections = {
+      'my_files: {
+         'driver': 'function',
+         'source': my_own_data,
+         'target': 'my_data/my_file.txt'
+         'write_result': True
+         }
+      }
+   }
+
+The specified function gets 1 argument during the call: A dictionary which contains the complete configuration of the
+collection.
+
+If return value is not None, the returned data is written to the file specified by ``target``.
+
+Options
+-------
+
+write_result
+~~~~~~~~~~~~
+
+If ``write_result`` is False, no data is written by the driver.
+But this could be done by the function itself.
+
+**Default**: ``True``
+
+

docs/drivers/index.rst

@@ -3,8 +3,69 @@
 Drivers
 =======
 
+Drivers represents the technical function, which gets configured by the configuration given by a collection.
+
+Each collection must reference a single driver, which cares about:
+
+* Initial clean up
+* Configured execution
+* Final clean up
+
+``Sphinx-Collections`` already provides some major drivers, which support different use case.
+
 .. toctree::
    :maxdepth: 1
 
    copy_folder
-   copy_file
+   copy_file
+   string
+   function
+   report
+
+Own drivers
+-----------
+
+You can specify own drivers directly inside your ``conf.py`` file.
+
+Using own drivers instead of e.g. a pure function call has several advantages:
+
+* Configuration handling.
+* Correct and easy logging.
+* Executed during correct Sphinx phases.
+* Integrated clean-up.
+* Report capabilities.
+
+.. code-block::
+
+    from sphinxcontrib.collections.drivers import Driver
+    from sphinxcontrib.collections.api import register_driver
+
+
+    class myDriver(Driver):
+        def run(self):
+            self.info('Run for source {}'.format(self.config['source']))
+
+        def clean(self):
+            self.info('Clean')
+
+    register_driver('my_driver', myDriver)
+
+    collections = {
+        'my_river_test': {
+            'driver': 'my_driver',
+            'source': '../tests/dummy/',
+            'active': True,
+        },
+
+If you have created an awesome driver, please consider to provide 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!
+
+Driver class
+~~~~~~~~~~~~
+
+.. autoclass:: sphinxcontrib.collections.drivers.Driver
+   :members:
+   :undoc-members:
+   :private-members:
+   :special-members: __init__

docs/drivers/report.rst

@@ -0,0 +1,28 @@
+report
+======
+
+Creates a collection report in file specified by ``target``.
+
+Please be sure to specify this report as one of the latest collections, otherwise other
+collections have not been executed before this report gets generated.
+
+.. code-block:: python
+
+    collections = {
+      'my_collection_report: {
+         'driver': 'report',
+         'target': 'reports/collections.rst'
+         }
+      }
+   }
+
+
+The following template is used to build the report:
+
+.. literalinclude:: ../../sphinxcontrib/collections/drivers/report.rst.template
+
+**Example**:
+
+This is the report of the latest run for this documentation.
+
+.. literalinclude:: /_collections/doc_collection_report.rst

docs/drivers/string.rst

@@ -0,0 +1,43 @@
+string
+======
+
+Copies a string defined in ``source`` into a file specified by ``target``.
+
+.. code-block:: python
+
+    collections = {
+      'my_files: {
+         'driver': 'string',
+         'source': 'Awesome, this is nice',
+         'target': 'my_data/my_file.txt'
+         }
+      }
+   }
+
+You can also use more complex strings by assigning them to a variable.
+
+.. code-block:: python
+
+    my_string = """
+    Headline
+    ========
+
+    Ohh **awesome**!
+
+    Multiline!
+
+    .. codeblock:: rst
+
+       Works also
+       ----------
+    """
+
+    collections = {
+      'my_files: {
+         'driver': 'string',
+         'source': my_string,
+         'target': 'my_data/my_file.txt'
+         }
+      }
+   }
+

setup.py

@@ -4,7 +4,7 @@
 import os
 from setuptools import setup, find_packages
 
-requires = ['sphinx>2.0']
+requires = ['sphinx>2.0', 'jinja2']
 
 setup(
     name='sphinx-collections',

sphinxcontrib/collections/__init__.py

@@ -1 +1 @@
-from sphinxcontrib.collections.collections import setup  # NOQA
+from sphinxcontrib.collections.main import setup  # NOQA

sphinxcontrib/collections/api.py

@@ -0,0 +1,16 @@
+from sphinxcontrib.collections.collections import DRIVERS
+from sphinxcontrib.collections.drivers import Driver
+
+
+def register_driver(name, driver_class):
+    if not issubclass(driver_class, Driver):
+        raise SphinxCollectionsApiError('Given driver class must be a subclass of the main Driver class.')
+
+    try:
+        DRIVERS[name] = driver_class
+    except KeyError:
+        raise SphinxCollectionsApiError('Driver with name {} already exists.'.format(name))
+
+
+class SphinxCollectionsApiError(BaseException):
+    pass

sphinxcontrib/collections/collections.py

@@ -1,11 +1,13 @@
-import os
 import sphinx
+import os
 
 from pkg_resources import parse_version
 
 from sphinxcontrib.collections.drivers.copy_folder import CopyFolderDriver
 from sphinxcontrib.collections.drivers.copy_file import CopyFileDriver
-from sphinxcontrib.collections.directives.if_collection import CollectionsIf, CollectionsIfDirective
+from sphinxcontrib.collections.drivers.string import StringDriver
+from sphinxcontrib.collections.drivers.function import FunctionDriver
+from sphinxcontrib.collections.drivers.report import ReportDriver
 
 sphinx_version = sphinx.__version__
 if parse_version(sphinx_version) >= parse_version("1.6"):
@@ -15,49 +17,18 @@
 
     logging.basicConfig()  # Only need to do this once
 
-
 LOG = logging.getLogger(__name__)
-VERSION = 0.1
 COLLECTIONS = []
 
 DRIVERS = {
     'copy_folder': CopyFolderDriver,
-    'copy_file': CopyFileDriver
+    'copy_file': CopyFileDriver,
+    'string': StringDriver,
+    'function': FunctionDriver,
+    'report': ReportDriver,
 }
 
 
-def setup(app):
-    """
-    Configures Sphinx
-
-    Registers:
-
-    * config values
-    * receivers for events
-    * directives
-    """
-
-    # Registers config options
-    app.add_config_value('collections', {}, 'html')
-    app.add_config_value('collections_target', '_collections', 'html')
-    app.add_config_value('collections_clean', True, 'html')
-    app.add_config_value('collections_final_clean', True, 'html')
-
-    # Connects handles to events
-    app.connect('config-inited', collect_collections)
-    app.connect('config-inited', clean_collections)
-    app.connect('config-inited', execute_collections)
-    app.connect('build-finished', final_clean_collections)
-
-    app.add_node(CollectionsIf)
-    app.add_directive('if-collection', CollectionsIfDirective)
-    app.add_directive('ifc', CollectionsIfDirective)
-
-    return {'version': VERSION,
-            'parallel_read_safe': True,
-            'parallel_write_safe': True}
-
-
 def collect_collections(app, config):
     LOG.info('Read in collections ...')
     for name, collection in config.collections.items():