Configuration

This document describes the design of the configuration settings for the Python classes and configuration files and tracks their implementation status.

We use symbols to indicate the status of implementation (see table below). For planned or in-progress work, we might include signatures, docstrings, and pseudocode to clarify the design. Once the interface is implemented, these are replaced by links to the reference documentation.

A table showing the symbols used to indicate the status of interface components, along with their descriptions.
Status	Description
	Interface that has been implemented.
	Interface that is currently being worked on.
	Interface that is planned, but isn’t being worked on currently.

Overview

Data Packages range from simple (a few resources) to complex (many resources with detailed schemas). So we designed Flower’s configuration to let you customise output file types, content and structure (via templates), and the output destination to fit different needs.

Configuration is split into two main levels:

The top-level configuration dictates whether to use a built-in style or a custom style, the location of the template files for a custom style, and which sections to include (see One and Many section classes for a definition of sections). This is represented by the Config class, the settings under the [tool.seedcase-flower] table in pyproject.toml, or the settings at the top level of the .flower.toml file. These configurations are only used by the build command and cannot be set on the CLI.
The style-level configuration dictates which contents of the datapackage.json (not individual properties) are included in each section of the documentation and where those sections are outputted. This is represented by one or more One and Many section classes or [[one]] and [[many]] tables in the sections.toml file in the template directory and cannot be set in pyproject.toml or .flower.toml.

Python classes

`Config`

The Config class specifies the top-level configurations used by build via three attributes: style, template_dir, and output_dir. See the Config for details on each attribute.

output_dir allows users to set the output location independently of how a style structures its files internally. It defaults to docs/.

Flower uses Jinja2 to generate documentation from datapackage.json. Because Jinja2 supports any plain text output format (e.g., .qmd via .qmd.jinja templates), output file types require no special handling when adding new built-in styles.

`One` and `Many` section classes

A “section” within the context of Flower is a unit of documentation output: one or more generated files that cover a specific part of the datapackage.json metadata, produced from a Jinja2 template. For example, a single index.qmd covering the overall package metadata is one section, while a set of per-resource files (e.g., resources/species_catalog.qmd, resources/location_catalog.qmd, resources/growth_records.qmd) is another. The One and Many classes handle the configuration of these sections: One creates one output file from multiple Content items, while Many creates one file per metadata item (e.g., per resource) from a single Content item.

One has the attributes output_path and contents, where contents is a list of Content items. Many shares output_path but instead of a contents list, it includes Content attributes (content, template_path, jinja_variable) directly. Unlike One, Many does not support jsonpath. Instead, its content attribute is restricted to either "resources" or "fields", since only these metadata properties benefit from multi-file output.

output_path is relative to Config.output_dir. One.output_path must be a file path, while Many.output_path must point to a directory. In built-in styles, output_path is pre-configured and cannot be changed.

Many.output_path uses {} placeholders to produce one file per item; e.g., resources/{resource-name}.qmd creates one file per resource (a bare resources/ path is equivalent). For nested output, e.g., one file per field per resource, use resources/{resource-name}/fields/{resource-schema-field-name}.qmd. We use items’ name attribute for file naming, because the Data Package specification requires it to be lowercase with no spaces. Placeholder names like resource-name are used instead of name directly, since name exists at multiple nesting levels.

See One or Many for more details.

`Content`

The Content class maps specific properties to a Jinja2 template via three attributes: jsonpath, template_path, and jinja_variable. This class is used within the One section class. Content allows flexible documentation structures for both built-in and custom styles. Only the properties specified by Content.jsonpath are passed to the template (i.e., not the entire datapackage.json file).

See Content for more details.

Configuration file

Configuration files make documentation creation explicitly defined and reproducible with seedcase-flower build. Flower uses two types: the main configuration file and sections.toml.

We use TOML since it has many advantages for configuration, most notably comment support (#) and content treated as pure data (unlike YAML, which can contain executable code).

The main configuration maps one-to-one to the Config class. It can be placed in a standalone .flower.toml file or in pyproject.toml under the [tool.seedcase-flower] table. Flower resolves the configuration in this order, falling back to the next if not provided or found:

The style argument passed to the build CLI command.
The .flower.toml file in the working directory.
The [tool.seedcase-flower] table in pyproject.toml.
The default Config values, which represent the default built-in style.

The sections.toml file defines the style by configuring the One and Many classes, and must be present in the template directory (Config.template_dir). Built-in styles include this file internally while users must provide it in the template directory for their custom style.

Main config settings: `.flower.toml`

The .flower.toml file contains the main configuration settings for Flower. For a simple configuration using a built-in style, the file can be as simple as:

.flower.toml

style = "quarto-one-page"
output-dir = "docs/"

Custom styles require a template-dir. For example:

.flower.toml

template-dir = "path/to/templates/"
output-dir = "docs/"

The template-dir above must include at least one Jinja and a sections.toml file. When template-dir is given, any value in style is ignored.

Main config settings: `pyproject.toml`

The main configuration settings can also go in the pyproject.toml file under [tool.seedcase-flower]. This avoids an extra configuration file if the project already includes a pyproject.toml file.

The custom example from .flower.toml above would look like this in pyproject.toml:

[tool.seedcase-flower]
style = "custom"
template-dir = "templates/"
output-dir = "docs/"

Style config settings: `sections.toml`

sections.toml is kept at the root of Config.template_dir and defines the One, Many, and Content classes for a given style. For example:

#  Creates an `index.qmd` with `package` and `contributors`
# contents from Jinja2 templates.
[[one]]
output-path = "index.qmd"
[[one.contents]]
jsonpath = "."
template-path = "path/to/templates/package.qmd.jinja"
jinja-variable = "package"
[[one.contents]]
jsonpath = ".contributors"
template-path = "path/to/templates/contributors.qmd.jinja"
jinja-variable = "contributors"

# Creates one file per resource in a `docs/resources/` folder.
# E.g. `docs/resources/growth-records.qmd`,
# `docs/resources/species-catalog.qmd`, etc.
[[many]]
output-path = "resources/"
# Or equivalently
# output-path = "resources/{resource-name}.qmd"
content = "resources"
template-path = "path/to/templates/resource.qmd.jinja"
jinja-variable = "resource"

#  Creates one YAML file per field in each resource.
# `{resource-name}` and `{field-name}` are replaced with the resource
# and field names. This allows you to use custom Quarto listings:
# https://quarto.org/docs/websites/website-listings.html#yaml-listing-content
[[many]]
output-path = "resources/{resource-name}/{field-name}.yml"
content = "fields"
template-path = "path/to/templates/resource-schema-field.yml.jinja"
jinja-variable = "field"

Overview

Python classes

Config

One and Many section classes

Content