Usage: seedcase-flower COMMAND Flower generates human-readable documentation from Data Packages. ╭─ Commands ───────────────────────────────────────────────────────────────────╮ │ <build> Build human-readable documentation from a │ │ datapackage.json file. │ │ <view> Display the contents of a datapackage.json in a │ │ human-friendly way. │ │ --help Display this message and exit. │ │ --install-completion Install shell completion for this application. │ │ --version Display application version. │ ╰──────────────────────────────────────────────────────────────────────────────╯
Using the CLI
How to use Flower on the command-line.
Flower is designed to provide a friendly user experience from the command line. The CLI has commands for both viewing and building documentation from a Data Package’s metadata. The general pattern for how to use Flower from the CLI is:
Terminal
seedcase-flower COMMAND [ARGS] [OPTIONS]To get started, try calling the program without any commands, arguments, or options by typing seedcase-flower and pressing enter. This is the same as invoking the --help flag and will show the following text:
Terminal
seedcase-flowerViewing Data Package metadata
To view the metadata of a Data Package directly in the terminal, you can use the view command like so:
Terminal
seedcase-flower viewThe view command displays the metadata in an easy to read format that is optimized for display directly in the Terminal.
Working with a Data Package in a custom location
By default, view looks for a datapackage.json file in the current directory, but you can specify a different path if desired:
Terminal
seedcase-flower view another/directory/datapackage.jsonIt also is possible to point Flower to a Data Package that is available online. To do this, you can provide the full URL to the remote datapackage.json, e.g.
Terminal
seedcase-flower view https://raw.githubusercontent.com/seedcase-project/example-seed-beetle/refs/heads/main/datapackage.jsonFor Data Packages on GitHub (like for the URL used above), you can use the gh: prefix as a shortcut. For example, the long URL above can be shortened to the following:
Terminal
seedcase-flower view gh:seedcase-project/example-seed-beetleStyling the output
If you would like to customize the style of how the metadata is displayed, you can use the --style flag. This option allows you to format the output with any of the built-in styles:
Terminal
seedcase-flower view --style quarto-one-page gh:seedcase-project/example-seed-beetleThe view command can use any of built-in styles that includes all output on a single page. It is not compatible with multi-page styles.
Important
If you have set the style option in a configuration file read by Flower, you might be confused as to why it does not have an effect when calling seedcase-flower view --style .... The reason for this is that the view command by design completely ignores any configuration read from Flower’s configuration file, even those with the same name as the options passed to view. You can only configure view via command line flags.
For more details about what you can do with view, see:
Terminal
seedcase-flower view --helpBuilding documentation from Data Package metadata
In addition to viewing metadata in the terminal, Flower converts Data Package metadata into a set of plain text files that are more human-friendly than the datapackage.json. These files can be used to build a website for the documentation which can make your Data Package’s metadata more easily discoverable and readable. You can generate this set of files with the build command:
Terminal
seedcase-flower buildThis command generates one new file: docs/index.qmd. The qmd extension means that this file is a Quarto-flavored Markdown file. While this is the default text format, you can change it by specifying your own custom templates as detailed in the configuration section of this guide. Later in this guide, you will also see how you can generate more than one file by using different styles with build.
Changing input and output directory
By default, build will look for a datapackage.json file in the current directory, but you can use a different source location if you want (just like with view):
Terminal
seedcase-flower build another/directory/datapackage.jsonTo generate files in a different location, use the --output-dir flag with a folder name. For example:
Terminal
seedcase-flower build --output-dir my-dirThis will generate my-dir/index.qmd instead of docs/index.qmd.
Styling the output
Just like the view command, the build command accepts a --style option. This lets you choose how the metadata are organized according to one of the built-in styles. For example, to split the metadata for each resource in the Data Package into its own file, you can use the quarto-resource-listing style:
Terminal
seedcase-flower build --style quarto-resource-listingLike the default output style is quarto-one-page, the quarto-resource-listing style creates docs/index.qmd but it also creates a separate file for the data resource in the docs/resources/ folder, for example docs/resources/seed-beetle-metabolic-rate.qmd. You can read more about the available default styles and how to create your own custom style in the configuration section of the documentation.