Collections

Collections are defined by setting collections in conf.py:

collections = {
      '<COLLECTION_NAME>': {
         'driver': '<DRIVER>',
         'source': 'source path',
         '<COLLECTION_OPTION>': 'any value'
      }
   }

<COLLECTION_NAME> must be a string, which can also be used as folder name. So try to avoid special characters or other hashable objects.

driver must always be set and match a registered Driver.

Also source must always be specified. Its content is validated and used by the driver.

<COLLECTION_OPTION> should also be a string, which matches one of the options below. If it does not match, it gets ignored.

Collection Options

Most of the below options have a default value. Therefore setting them inside your configuration is not needed, if you are happy with the related default value.

However, options which are needed by drivers normally don’t have a default value. So please take a look into the related driver configuration to see what is needed and supported.

driver

Specifies the driver to use. Must be a string.

If not set or driver is unknown, an exception gets thrown.

For a complete list of drivers, please see Drivers.

Mandatory: Yes

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
    }
}

source

String of the source to use.

Depending on the used driver, this can be a folder, file, a git repository or whatever.

Mandatory: Yes

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
    }
}

target

Target path, where to store the new files. Depending on the driver this must be a folder or a single file.

Can be an absolute path or a relative path, which starts from the folder set by collections_target.

If not set, the collection name is used as target name.

Example:

If collections_target has default value _collections and collection is named my_first_collection, then target is set to _collections/my_first_collection inside your documentation project.

Hint

target must always be somewhere inside your documentation folder (where your conf.py is stored). Targets outside of your documentation are not supported.

Default: collection name

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
        'target': 'custom_folder/folder_x/'
    }
}

active

active can be set to True or False. If set to False, the collection gets completely ignored during documentation build.

Default: True

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
        'active': False
    }
}

safe

Takes a boolean value and if it is set to True any problem will raise an exception and stops the build.

Default: True

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'safe': False,
    }
}

clean

If set to False, no clean-up is taking place before collections get executed.

Default value can be changed for all collections by setting collections_clean

Default: True

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
        'clean': False
    }
}

final_clean

If set to True, a final clean up at the end of a Sphinx build is executed.

Often used to keep your working tree clean and have collected files only during build in related folders.

Default value can be changed for all collections by setting collections_final_clean.

Default: True

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
        'final_clean': False
    }
}

tags

List of tags, which trigger an activation of the collection. Should be used together with active set to False, otherwise the collection gets always executed.

collections = {
    'my_collection': {
        'driver': 'copy_folder',
        'source': 'source path',
        'active': False,
        'tags': ['my_collection', 'dummy']
    }
}

Use -t tag option of sphinx-build command to trigger related collections.

sphinx-build -b html -t dummy . _build/html

Driver Options

Options for drivers are also stored directly with the configuration for collections.

Please take a look into the specific Driver to get information about its additional configuration possibilities.