sphinxcontrib-constdata

sphinxcontrib-constdata is the extension for Sphinx documentation projects that allows showing values, listing tables, and generating links from CSV, JSON and YAML files.

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 is id. 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 contains variable, “ID column not found” error will appear. It also applies to the default value id - ID, iD, etc. will all cause the error.

    constdata_files = {
      "conf.yaml": {
          "id": "Variable"
      }
    
  • label – reStructuredText template for constdata:label role. See Templating.

    E.g., labels coming from shortcuts.yaml should be rendered with values from columns pc and mac on matching row.

    constdata_files = {
      "shortcuts.yaml": {
          "label": ":kbd:`{pc}` (PC) or :kbd:`{mac}` (Mac)"
      }
    
  • link – reStructuredText template for constdata:link role. See Templating.

    E.g., links to table listing conf.yaml should have the link title (link text) from id 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