From b80c3191d9c147c672f97c5dc4bb0536725af16f Mon Sep 17 00:00:00 2001 From: Luc Perkins Date: Thu, 11 Jul 2024 09:49:06 -0700 Subject: [PATCH] Use Markdown tables for config --- doc/manual/src/protocols/flake-schemas.md | 36 +++++++++++++---------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/doc/manual/src/protocols/flake-schemas.md b/doc/manual/src/protocols/flake-schemas.md index f6cdd6165..b1dfa5da6 100644 --- a/doc/manual/src/protocols/flake-schemas.md +++ b/doc/manual/src/protocols/flake-schemas.md @@ -8,34 +8,38 @@ every output type that you want to be supported. If a flake does not have a `sch A schema is an attribute set with the following attributes: -* `version`: Should be set to 1. -* `doc`: A string containing documentation about the flake output type in Markdown format. -* `allowIFD` (defaults to `true`): Whether the evaluation of the output attributes of this flake can read from derivation outputs. -* `inventory`: A function that returns the contents of the flake output (described below). +| Attribute | Description | Default | +| :---------- | :---------------------------------------------------------------------------------------------- | :------ | +| `version` | Should be set to 1 | | +| `doc` | A string containing documentation about the flake output type in Markdown format. | | +| `allowIFD` | Whether the evaluation of the output attributes of this flake can read from derivation outputs. | `true` | +| `inventory` | A function that returns the contents of the flake output (described [below](#inventory)). | | # Inventory -The `inventory` function returns a *node* describing the contents of the flake output. A node is either a *leaf node* or a *non-leaf node*. This allows nested flake output attributes to be described (e.g. `x86_64-linux.hello` inside a `packages` output). +The `inventory` function returns a _node_ describing the contents of the flake output. A node is either a _leaf node_ or a _non-leaf node_. This allows nested flake output attributes to be described (e.g. `x86_64-linux.hello` inside a `packages` output). Non-leaf nodes must have the following attribute: -* `children`: An attribute set of nodes. If this attribute is missing, the attribute if a leaf node. +| Attribute | Description | +| :--------- | :------------------------------------------------------------------------------------- | +| `children` | An attribute set of nodes. If this attribute is missing, the attribute is a leaf node. | Leaf nodes can have the following attributes: -* `derivation`: The main derivation of this node, if any. It must evaluate for `nix flake check` and `nix flake show` to succeed. - -* `evalChecks`: An attribute set of Boolean values, used by `nix flake check`. Each attribute must evaluate to `true`. - -* `isFlakeCheck`: Whether `nix flake check` should build the `derivation` attribute of this node. - -* `shortDescription`: A one-sentence description of the node (such as the `meta.description` attribute in Nixpkgs). - -* `what`: A brief human-readable string describing the type of the node, e.g. `"package"` or `"development environment"`. This is used by tools like `nix flake show` to describe the contents of a flake. +| Attribute | Description | +| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `derivation` | The main derivation of this node, if any. It must evaluate for `nix flake check` and `nix flake show` to succeed. | +| `evalChecks` | An attribute set of Boolean values, used by `nix flake check`. Each attribute must evaluate to `true`. | +| `isFlakeCheck` | Whether `nix flake check` should build the `derivation` attribute of this node. | +| `shortDescription` | A one-sentence description of the node (such as the `meta.description` attribute in Nixpkgs). | +| `what` | A brief human-readable string describing the type of the node, e.g. `"package"` or `"development environment"`. This is used by tools like `nix flake show` to describe the contents of a flake. | Both leaf and non-leaf nodes can have the following attributes: -* `forSystems`: A list of Nix system types (e.g. `["x86_64-linux"]`) supported by this node. This is used by tools to skip nodes that cannot be built on the user's system. Setting this on a non-leaf node allows all the children to be skipped, regardless of the `forSystems` attributes of the children. If this attribute is not set, the node is never skipped. +| Attribute | Description | +| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `forSystems` | A list of Nix system types (e.g. `["x86_64-linux"]`) supported by this node. This is used by tools to skip nodes that cannot be built on the user's system. Setting this on a non-leaf node allows all the children to be skipped, regardless of the `forSystems` attributes of the children. If this attribute is not set, the node is never skipped. | # Example