From 9a0777049cfe11e011316929f197629d866bd957 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antti=20Kivim=C3=A4ki?= Date: Fri, 8 Nov 2024 13:18:37 +0200 Subject: [PATCH] docs: spelling corrections --- cmd/docs/templates/_schema.tmpl | 22 +++++++++---------- docs/site/docs/installation.mdx | 14 ++++++------ docs/site/docs/intro.mdx | 10 ++++----- docs/site/docs/usage.mdx | 38 ++++++++++++++++----------------- 4 files changed, 42 insertions(+), 42 deletions(-) diff --git a/cmd/docs/templates/_schema.tmpl b/cmd/docs/templates/_schema.tmpl index 3bb0b80c..d26a777a 100644 --- a/cmd/docs/templates/_schema.tmpl +++ b/cmd/docs/templates/_schema.tmpl @@ -8,10 +8,10 @@ | `apiVersion` | `string` | `v1` | Version of the recipe metadata API schema. Currently should have value "v1". | | `name` | `string` | | Name of the recipe. | | `version` | `string` | | Version of the recipe. Must be valid [semver](https://semver.org/). | -| `description` | `string` | | Description of what the recipe does | +| `description` | `string` | | Description of what the recipe does. | | `source` | `string` | | URL to source code for this recipe. | | `templateExtension` | `string` | | File extension of files in "templates" directory which should be templated. Files not matched by this extension will be copied as-is. If left empty (the default), all files will be templated. | -| `initHelp` | `string` | | A message which will be showed to an user after a succesful recipe execution. Can be used to guide the user what should be done next in the project directory. Supports templating | +| `initHelp` | `string` | | A message which will be shown to an user after a successful recipe execution. Can be used to guide the user on what should be done next in the project directory. Supports templating. | | `ignorePatterns` | `[]string` | | Glob patterns for ignoring generated files from future recipe upgrades. Ignored files will not be regenerated even if their templates change in future versions of the recipe. | | `vars` | [`[]Variable`](#variable) | | An array of variables which can be used in templates. The user will be prompted to provide the value for the variable if not set with `--set` flag. | @@ -21,16 +21,16 @@ | Attribute | Type | Default | Description | | --- | --- | --- | --- | -| `name` | `string` | | The name of the variable. It is also used as unique identifier, so two variables can not have the same name. | +| `name` | `string` | | The name of the variable. It is also used as an unique identifier, so two variables cannot have the same name. | | `description` | `string` | | Description of the variable. Will be shown to the user when "show help" is activated. | | `default` | `string` | | Default value of the variable. | -| `confirm` | `bool` | `false` | If set to true, the prompt will be yes/no question, and the value type will be boolean. | +| `confirm` | `bool` | `false` | If set to true, the prompt will be a yes/no question, and the value type will be boolean. | | `optional` | `bool` | `false` | If set to true, the variable can be left empty. | | `options` | `[]string` | | The user selects the value from a list of options. | | `multi` | `bool` | `false` | If set to true, the user can select multiple options defined by the `options` property. | | `validators` | [`[]Validator`](#validator) | | Validators for the variable. | | `if` | `string` | | Makes the variable conditional based on the result of the expression. The result of the evaluation needs to be a boolean value. Uses https://github.com/expr-lang/expr. | -| `columns` | `[]string` | | Set the variable as a table type with columns defined by this property. | +| `columns` | `[]string` | | Set the variable as a table type with columns defined by this property. | ### Validator @@ -50,8 +50,8 @@ | Attribute | Type | Default | Description | | --- | --- | --- | --- | | `values` | `map[string]any` | | Values to use to render the recipe templates. Map key is the name of the variable and value is the variable value. | -| `expectedInitHelp` | `string` | | Expected initHelp of the recipe when rendered with the values specified in the test | -| `ignoreExtraFiles` | `bool` | | If true, test will pass even though templates generated more files than the test specifies. This is useful when creating specific test cases for large recipes. | +| `expectedInitHelp` | `string` | | Expected initHelp of the recipe when rendered with the values specified in the test. | +| `ignoreExtraFiles` | `bool` | | If true, the test will pass even though templates generated more files than the test specifies. This is useful when creating specific test cases for large recipes. | ## Sauce schema (`sauces.yml`) @@ -61,9 +61,9 @@ | --- | --- | --- | --- | | `apiVersion` | `string` | `v1` | Version of the sauce API schema. Currently should have value "v1". | | `recipe` | [`Recipe`](#recipe-schema-recipeyml) | | The recipe which was used to render the sauce. | -| `values` | `map[string]any` | | Values which was used to execute the recipe. | -| `files` | `map[string]File` | | Files genereated from the recipe | -| `id` | `string` | | Random unique ID whose value is determined on first render and stays the same on subsequent re-renders (upgrades) of the sauce. Can be used for example as a seed for template random functions to provide same result on each template. | +| `values` | `map[string]any` | | Values which were used to execute the recipe. | +| `files` | `map[string]File` | | Files generated by the recipe. | +| `id` | `string` | | Random unique ID whose value is determined on first render and stays the same on subsequent re-renders (upgrades) of the sauce. Can be used for example as a seed for template random functions to provide the same result on each template. | | `from` | `string` | | Defines the repository where updates should be checked for the recipe. | | `subpath` | `string` | | Subpath which is used as a path prefix when saving and loading the sauce files. This is commonly used in monorepos. | @@ -85,6 +85,6 @@ | `name` | `string` | | The name of the recipe. | | `version` | `string` | | The version of the recipe. | | `repository` | `string` | | The repository where the recipe is located. Can be a local path or remote URL. | -| `values` | `map[string]any` | | Values which was used to execute the recipe. | +| `values` | `map[string]any` | | Values which were used to execute the recipe. | {{- end }} \ No newline at end of file diff --git a/docs/site/docs/installation.mdx b/docs/site/docs/installation.mdx index 5aecbfd4..269fd5d8 100644 --- a/docs/site/docs/installation.mdx +++ b/docs/site/docs/installation.mdx @@ -33,15 +33,15 @@ winget upgrade jalapeno Cross-platform binaries are provided with each release of Jalapeno. These can manually be downloaded and installed from [GitHub releases](https://github.com/futurice/jalapeno/releases/). -In short the process is: +In short, the process is: 1. Download [the latest version of Jalapeno](https://github.com/futurice/jalapeno/releases/latest) for your platform 2. Extract the archive 3. Make the binary executable -4. Rename and move the binary to proper location +4. Rename and move the binary to the proper location -For example on MacOS (running on Apple Silicon) this can be done with: +For example, on macOS (running on Apple Silicon) this can be done with: ```bash curl -L https://github.com/futurice/jalapeno/releases/latest/download/jalapeno-darwin-arm64.tar.gz -o jalapeno.tar.gz @@ -52,11 +52,11 @@ mv jalapeno /usr/local/bin/jalapeno ## Use via Docker -It is possible to use Jalapeno via Docker without installing it locally. Jalapeno image is available +It is possible to use Jalapeno via Docker without installing it locally. The Jalapeno image is available from the GitHub Container Registry, and thus the following command on a \*nix system is equivalent to running `jalapeno` locally: -```bash tab={"label":"MacOS and Linux"} +```bash tab={"label":"macOS and Linux"} docker run -it --rm -v $(pwd):/workdir ghcr.io/futurice/jalapeno:latest ``` @@ -73,7 +73,7 @@ docker run -it --rm -v ${PWD}:/workdir ghcr.io/futurice/jalapeno:latest First, make sure you have [Go](https://go.dev/doc/install) and [Task](https://taskfile.dev/installation) installed. -Then you can compile the binary with following commands: +Then you can compile the binary with the following commands: ```bash git clone https://github.com/futurice/jalapeno.git @@ -81,4 +81,4 @@ cd jalapeno task build ``` -After this the binary is available on path `./bin/jalapeno`. +After this, the binary is available on the path `./bin/jalapeno`. diff --git a/docs/site/docs/intro.mdx b/docs/site/docs/intro.mdx index 104f203a..0cf36368 100644 --- a/docs/site/docs/intro.mdx +++ b/docs/site/docs/intro.mdx @@ -9,14 +9,14 @@ hide_title: true -Jalapeno is **a templating system** which support complex templating while staying user friendly. Templates used by Jalapeno are called _recipes_. +Jalapeno is **a templating system** which supports complex templating while staying user-friendly. Templates used by Jalapeno are called _recipes_. To get started, [install](/installation) the tool and follow the [getting started](/usage#getting-started) guide. ## Features -- **Easy to use templates**: The CLI guides the user as much as possible when using recipes. This is done by prompting the user interactively for required template values, providing validation for the values, giving hints about what to do after executing the recipe etc. +- **Easy to use templates**: The CLI guides the user as much as possible when using recipes. This is done by prompting the user interactively for required template values, providing validation for the values, giving hints about what to do after executing the recipe, etc. - **Modular**: A project can use multiple recipes at the same time, so you can compose your projects from multiple smaller template modules. This helps to keep the recipes simple and focused. -- **Continous integration**: Recipes are versioned, and new versions of the recipe can be merged to existing projects. Recipes can be shared via OCI compatible registries (aka container registries) so project CI/CD pipelines which already utilize the registry can easily check and notify the developers if there are new versions available for the recipes. -- **Tweakable templates**: Since every project is a little bit different, manual tweaks are often needed after a recipe has been executed. Jalapeno can still update the recipes used in a project by detecting which files has been manually edited and solve the merge conflicts. This way the project can stay up to date with the recipe, while still keeping the manual tweaks. -- **Snapshots tests**: Recipes can be tested with snapshot tests, which reduces regression when developing the templates by ensuring that the templates produces expected outputs. +- **Continuous integration**: Recipes are versioned, and new versions of the recipe can be merged into existing projects. Recipes can be shared via OCI compatible registries (aka container registries) so project CI/CD pipelines which already utilize the registry can easily check and notify the developers if there are new versions available for the recipes. +- **Tweakable templates**: Since every project is a little bit different, manual tweaks are often needed after a recipe has been executed. Jalapeno can still update the recipes used in a project by detecting which files have been manually edited and solving the merge conflicts. This way the project can stay up to date with the recipe, while still keeping the manual tweaks. +- **Snapshot tests**: Recipes can be tested with snapshot tests, which reduces regression when developing the templates by ensuring that the templates produce expected outputs. diff --git a/docs/site/docs/usage.mdx b/docs/site/docs/usage.mdx index ff23195d..94c3d326 100644 --- a/docs/site/docs/usage.mdx +++ b/docs/site/docs/usage.mdx @@ -89,7 +89,7 @@ The rest of the files are rendered from the templates. You can edit the template ## Templating -Templates are done by using [Go templates](https://pkg.go.dev/text/template). Examples how to write these templates can be found in [this article](https://www.digitalocean.com/community/tutorials/how-to-use-templates-in-go#step-4-writing-a-template) and in the [example recipe](https://github.com/futurice/jalapeno/blob/main/examples/variable-types/templates/README.md?plain=1). +Templates are done by using [Go templates](https://pkg.go.dev/text/template). Examples of how to write these templates can be found in [this article](https://www.digitalocean.com/community/tutorials/how-to-use-templates-in-go#step-4-writing-a-template) and in the [example recipe](https://github.com/futurice/jalapeno/blob/main/examples/variable-types/templates/README.md?plain=1). The following context is available on the templates: @@ -98,7 +98,7 @@ The following context is available on the templates: - `.Recipe.Name`: The name of the recipe - `.Recipe.Version`: The current version of the recipe - `.Recipe.Source`: URL to source code for this recipe -- `.ID`: An UUID which is generated after the first execution of the recipe. It can be used to generate unique pseudo-random values which stays the same over the upgrades, for example `my-resource-{{ sha1sum .ID | trunc 5 }}` +- `.ID`: An UUID which is generated after the first execution of the recipe. It can be used to generate unique pseudo-random values which stay the same over the upgrades, for example `my-resource-{{ sha1sum .ID | trunc 5 }}` - `.Variables`: Object which contains the values of the variables defined for the recipe. Example: `{{ .Variables.FOO }}` :::tip @@ -119,11 +119,11 @@ By defining `templateExtension` property in the `recipe.yml` file, you can defin ## Variables -Recipe variables let you define values which user need to provide to be able to render the tempaltes. Variables are defined in the `recipe.yml` file. You can check schema [here](/api#variable). +Recipe variables let you define values which users need to provide to be able to render the templates. Variables are defined in the `recipe.yml` file. You can check the schema [here](/api#variable). ### Variable types -Recipe variables supports the following types: +Recipe variables support the following types: - [String](https://github.com/futurice/jalapeno/blob/main/examples/variable-types/recipe.yml#L9-L11) - [Boolean](https://github.com/futurice/jalapeno/blob/main/examples/variable-types/recipe.yml#L13-L15) @@ -135,7 +135,7 @@ You can see examples of all the possible variables in the [example recipe](https :::note -If you need to use numbers in the templates, you can use the `atoi` function to convert a string variable to integer: `{{ .Variables.FOO | atoi }}` +If you need to use numbers in the templates, you can use the `atoi` function to convert a string variable to an integer: `{{ .Variables.FOO | atoi }}` ::: @@ -145,11 +145,11 @@ Variables can be validated by defining [`validators`](/api#variable) property fo ## Publishing recipes -Jalapeno supports publishing and storing recipes in OCI compatible registries. This means that versioned recipes can be pushed and pulled to/from ordinary Container Registries. This is useful when you want to make your recipes available or you want to check for updates for the recipe manually or programatically from CI/CD pipeline. +Jalapeno supports publishing and storing recipes in OCI-compatible registries. This means that versioned recipes can be pushed and pulled to/from ordinary Container Registries. This is useful when you want to make your recipes available or you want to check for updates for the recipe manually or programmatically from a CI/CD pipeline. ### Pushing a recipe to Container registry -You can push a recipe to a Container registry by using `jalapeno push` command. For authentication you can use `docker login` before pushing the recipe or provide credentials directly to `jalapeno push` command by using flags. For example: +You can push a recipe to a Container registry by using the `jalapeno push` command. For authentication, you can use `docker login` before pushing the recipe or provide credentials directly to the `jalapeno push` command by using flags. For example: ```bash jalapeno create recipe my-recipe @@ -160,7 +160,7 @@ docker login ghcr.io -u my-user jalapeno push my-recipe ghcr.io/my-user/my-recipe ``` -After this you should be able to see the recipe in the Container registry from the UI or by running: +After this, you should be able to see the recipe in the Container registry from the UI or by running: ```bash docker inspect ghcr.io/my-user/my-recipe:v0.0.0 @@ -168,13 +168,13 @@ docker inspect ghcr.io/my-user/my-recipe:v0.0.0 :::note -The tag of the recipe in Container Registry is automatically determined by the version in `recipe.yml` file. So if you want to push a new version of the recipe, you need to update the version in `recipe.yml` file first. If you want to use `latest` tag, set `--latest` flag when pushing the recipe. +The tag of the recipe in Container Registry is automatically determined by the version in the `recipe.yml` file. So if you want to push a new version of the recipe, you need to update the version in the `recipe.yml` file first. If you want to use the `latest` tag, set the `--latest` flag when pushing the recipe. ::: ### Executing a recipe from Container registry -You can execute a recipe directly from Container registry by using `jalapeno execute` command. For example: +You can execute a recipe directly from Container registry by using the `jalapeno execute` command. For example: ```bash mkdir my-project && cd my-project @@ -214,7 +214,7 @@ jalapeno execute ./path/to/manifest.yml -d my-project ### Checking updates for a recipe -After you have executed a recipe, Jalapeno will create a `.jalapeno/sauces.yml` file to the project directory. This file contains information about the executed recipes and their versions. If the recipe was executed directly from a Container Registry, the registry URL is also stored in the file for checking for new versions. To check the new versions for the recipes, you can run: +After you have executed a recipe, Jalapeno will create a `.jalapeno/sauces.yml` file in the project directory. This file contains information about the executed recipes and their versions. If the recipe was executed directly from a Container Registry, the registry URL is also stored in the file for checking for new versions. To check the new versions for the recipes, you can run: ```bash jalapeno check @@ -226,7 +226,7 @@ This will check for updates for all the recipes in the project directory. You ca jalapeno check --recipe my-recipe ``` -If you've executed the recipe from local directory and the registry URL is still unknown, you can set the registry URL manually by running: +If you've executed the recipe from a local directory and the registry URL is still unknown, you can set the registry URL manually by running: ```bash jalapeno check --recipe my-recipe --from oci://ghcr.io/my-user/my-recipe @@ -234,7 +234,7 @@ jalapeno check --recipe my-recipe --from oci://ghcr.io/my-user/my-recipe :::tip -If you want to run the check in a CI/CD pipeline (like Github Actions), you can check the [`examples/github-action`](https://github.com/futurice/jalapeno/tree/main/examples/github-action) recipe how to do it or you can execute it to your project with `jalapeno execute oci://ghcr.io/futurice/jalapeno/examples/github-action:v0.0.0`. +If you want to run the check in a CI/CD pipeline (like Github Actions), you can check the [`examples/github-action`](https://github.com/futurice/jalapeno/tree/main/examples/github-action) recipe on how to do it or you can execute it in your project with `jalapeno execute oci://ghcr.io/futurice/jalapeno/examples/github-action:v0.0.0`. ::: @@ -252,20 +252,20 @@ You can upgrade a recipe by running: jalapeno upgrade oci://ghcr.io/my-user/my-recipe:v2.0.0 ``` -Note that the new recipe version needs to be same or newer than the previous version. Doing rollbacks with the `upgrade` command is not supported at the moment. +Note that the new recipe version needs to be the same or newer than the previous version. Doing rollbacks with the `upgrade` command is not supported at the moment. If you've modified the files which were originally generated by the recipe, Jalapeno will notice them while doing the upgrade. It will ask if you want to overwrite the modified files with the newer versions or keep the modified ones. ## Updating recipe version and changelog -You can update recipe version number and write a changelog with +You can update the recipe version number and write a changelog with ```bash jalapeno bumpver path/to/recipe -```` +``` -This will prompt you for the semver increment (patch/minor/major) of the update and an optional multiline comment for changelog. Ctrl+S exits multiline editor and saves your changes. -If a changelog doesn't already exist for a given recipe, `bumpver` will initialise it with the current version number and message "Init version" +This will prompt you for the semver increment (patch/minor/major) of the update and an optional multiline comment for the changelog. Ctrl+S exits the multiline editor and saves your changes. +If a changelog doesn't already exist for a given recipe, `bumpver` will initialize it with the current version number and message "Init version" You can alternatively specify a version number and message directly with @@ -292,7 +292,7 @@ my-recipe └── test.yml ``` -The [`test.yml`](http://localhost:3001/jalapeno/api#test-schema-testyml) file contains the configuration for the test case which will be executed when running `jalapeno test` command. The configuration contains for example the values for the template variables which should be used when rendering the recipe. The `files` directory contains the expected files which the recipe should generate. You can add more test cases by creating new directories under the `tests` directory. In this case, the test case name is `example`. +The [`test.yml`](http://localhost:3001/jalapeno/api#test-schema-testyml) file contains the configuration for the test case which will be executed when running the `jalapeno test` command. The configuration contains, for example, the values for the template variables which should be used when rendering the recipe. The `files` directory contains the expected files which the recipe should generate. You can add more test cases by creating new directories under the `tests` directory. In this case, the test case name is `example`. To update the current recipe output as the expected output to all tests, you can run: