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