Configuration¶
sphinxcontrib-constdata expects configuration via multiple constdata_*
variables in conf.py
.
constdata_root¶
- constdata_root¶
Relative path to a folder with external flatfiles in CSV, JSON or YAML format. Path is relative to conf.py
. Default value is _costdata
.
constdata_files¶
- constdata_files¶
Configuration of individual flatfiles. It is a dict (a mapping) of flatfiles to their configuration. The key is path to a flatfile (including suffix), relative to constdata_root
.
constdata_files = {
"menu.yaml": {
# ..configuration..
},
"path/to/shortcuts.yaml": {
# ..configuration..
}
}
The value is actual configuration for a flatfile (the most important are templates). It is also a dict. Available keys are:
id
– name of ID column. By default it isid
. If ID column has different name, you have to tell it here.The ID column name is case sensitive. E.g., if you set
Variable
, but the file containsvariable
, “ID column not found” error will appear. It also applies to the default valueid
-ID
,iD
, etc. will all cause the error.constdata_files = { "conf.yaml": { "id": "Variable" }
label
– reStructuredText template forconstdata:label
role. See Templating.E.g., labels coming from
shortcuts.yaml
should be rendered with values from columnspc
andmac
on matching row.constdata_files = { "shortcuts.yaml": { "label": ":kbd:`{pc}` (PC) or :kbd:`{mac}` (Mac)" }
link
– reStructuredText template forconstdata:link
role. See Templating.E.g., links to table listing
conf.yaml
should have the link title (link text) fromid
column rendered as inline literal.constdata_files = { "conf.yaml": { "link": "``{id}``" }
Caution
Current version of sphinxcontrib-constdata doesn’t allow table templates (how are table rendered). We know it and hopefully fix it soon. Thanks for your patience!
constdata_files_encoding¶
- constdata_files_encoding¶
Encoding used for reading flatfiles. By default, it is platform specific. We recommend set it to standard UTF-8.
constdata_files_encoding = "utf-8"
See Encoding.
constdata_csv_format¶
- constdata_csv_format¶
Customize the format of CSV files. Value is a dict of attributes and values.
sphinxcontrib-constdata uses standard Python 3 csv module which allows to customize the format of your CSV files. See csv module Formatting Parameters documentation for list of attributes.
constdata_csv_format = {
"delimiter": ";",
"doublequote": False
}
See CSV format.
Previous: Installation | Next: Flatfiles