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

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

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.

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_driver_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 . This would help our little Sphinx community a lot. Thanks!

Driver class

class sphinxcontrib.collections.drivers.Driver(collection, config=None)

__init__(collection, config=None)

Initialize self. See help(type(self)) for accurate signature.

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.

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

Parameters

message – string

Returns

None

run()

Is the main routine for the driver.

Must be implement by the parent driver class.