Drivers

Drivers represent the tasks which get configured by a collection’s configuration.

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 cases.

• copy_file
• copy_folder
• function
• git
• jinja
• report
• string
• symlink

Custom drivers

You can create your own drivers directly inside your conf.py file.

Creating your own drivers has several advantages:

• Configuration handling.

• Correct and easy logging.

• Ensure execution during correct Sphinx phases.

• Integrated clean-up.

• Report capabilities.

from sphinx_collections.drivers import Driver
from sphinx_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_driver_test': {
        'driver': 'my_driver',
        'source': '../tests/dummy/',
        'active': True,
    },
}

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!

Driver class

class sphinx_collections.drivers.Driver(collection, config=None)

__init__(collection, config=None)

clean()

Cares about cleaning up the working space from actions performed in run().

Gets called normally at the beginning and add the end of collection handling.

Must be implement by the parent driver class.

debug(message)

Writes a log message of level DEBUG.

Sets collection and driver information as prefix in front of the message

Parameters:

message – string

Returns:

None

error(message, e=None)

Raises exception, if driver is in safe mode. Otherwise just a log message gets printed.

Parameters:

• message – String

• e – Traceback object

Returns:

None

get_path(path)

Returns absolute path. If path is given as relative path, the absolute path is calculated taking documentation confdir as base folder.

Returns:

path string

get_source_path()

Returns absolute source path. If source was configured as relative path, the absolute path is calculated taking documentation confdir as base folder.

Returns:

path string

info(message)

Writes a log message of level INFO.

Prefixes collection information and driver name in front of the message.

Parameters:

message – string

Returns:

None

run()

This is the main routine for the driver.

The run method must be implement by the subclassed driver.