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.

Getting a single value

:constdata:label:

Lookup and print a single value in the file by its ID.

Takes URI telling which flatfile and ID of a row inside a flatfile as an URI query parameter. For example:

Go to the :constdata:label:`menu.yaml?FileSaveAs` option.

will lookup row with ID FileSaveAs in menu.yaml.

Flatfile path is relative to constdata_root folder (_constdata by default).

Tutorial

Label role is the most common markup added by sphinxcontrib-constdata.

  1. At the project root, create _constdata folder. External file supported formats are CSV/JSON/YAML. For example, menu.yaml:

    - id: FileNew
      Path: File --> Create and &open new file
    - id: FileSaveAs
      Path: File --> Save As...
    
  2. In conf.py, set the template that will be used to render values from the file. We want to print menu path (column Path) within :menuselection::

    constdata_files = {
       "menu.yaml": {
          "label": ":menuselection:`{Path}`"
       }
    }
    
  3. Somewhere in a reStructuredText document, use link role to print a value from menu.yaml:

    Go to the :constdata:label:`menu.yaml?FileSaveAs` option.
    
  4. This says that labels coming from menu.yaml should be rendered with value in column Path wrapped into :menuselection: role. Actual output (before Sphinx will process it) will be now:

    Go to the :menuselection:`File --> Save As...` option.
    
  5. The result is:

    Go to the File ‣ Save As… option.

Previous: Flatfiles | Next: Listing a table