Configuration

Configuring Flower with different settings and output options.

There are three ways to configure Flower:

  1. Via the command line interface (CLI), as described in the CLI guide.
  2. Via the Python interface, if using Flower as a Python library, which we don’t cover in any guide as we built Flower to be used as a CLI tool.
  3. Via a configuration file, as described below.

If you use the CLI (or the Python interface) to configure Flower’s output, Flower will not use the settings in the configuration file. If there are no configuration settings given in either the CLI, the Python interface, or in the configuration file, Flower will use its defaults.

Note

The source can only be specified via the CLI or the Python interface, not from the configuration file. Similarly, you can only configure the view command from the CLI or the Python interface, not from the configuration file.

The configuration file

Flower will read the configurations from either .flower.toml or pyproject.toml (not both) in this order of preference:

  1. .flower.toml
  2. pyproject.toml

If your Data Package is already a Python package, it might be convenient to configure Flower via pyproject.toml, since you likely already have your configuration settings for other Python tools in this file. Ultimately, which file you choose to use depends on if you prefer to have a separate configuration file for separate tools or if your prefer them in the same configuration file.

Configurable settings

Before diving into editing your configuration, let’s see which settings can be configured via the configuration file:

style
The style decides how the metadata is structured in the output files.
output-dir
The directory where Flower will save the output files.
template-dir
The directory that contains the template files to use. If you use this setting because you want to create your own style, then don’t add a style setting (it must be empty).

To see examples of which styles are available in Flower and how they would structure the metadata differently, see the examples page. When template-dir is used, the structure of the output is determined by a custom set of templates and configurations explained in the documentation about custom styles.

Configuration file syntax

To configure settings in Flower, open up .flower.toml in your favorite text editor. Let’s change the output directory to 'my-docs'. You can do this by adding the following line to the configuration:

.flower.toml
output-dir = "my-docs/"

When you run flower build, the configuration file will be read and the output directory will be changed to my-docs.

If you would like to change to use a custom style and instruct Flower to look for templates in the directory my-templates, you can write the following line to .flower.toml:

.flower.toml
template-dir = "my-templates/"

If you prefer to configure Flower via pyproject.toml instead, the syntax will be the same as we have seen above. The only difference is that a heading needs to be included to indicate where in the file Flower can find the settings. Open up pyproject.toml and add a new table header to the end as [tool.seedcase-flower]. Then put the same configuration settings as you used above in .flower.toml below this table header.

pyproject.toml
[tool.seedcase-flower]
template_dir = "my-templates/"
output_dir = "my-docs/"