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