From 980996a9f7fb5705ab5944eb60492aac9880aaf5 Mon Sep 17 00:00:00 2001 From: Kenneth Belitzky Date: Thu, 20 Aug 2026 18:15:51 -0300 Subject: [PATCH] docs: fix block end delimiter, slugify signature, and stale repo refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three documented behaviours did not match the implementation. 1. Block end delimiter was written as `%@}` in two places. template_renderer.py sets block_end_string='@%}'. Using `%@}` raises TemplateSyntaxError. template-variables.md contradicted itself: correct in the "Custom Delimiters" summary, wrong in "Block Syntax" below it. 2. `slugify` was documented as taking an optional separator argument. filters.py defines slugify(value) with no second parameter, so slugify(separator="_") raises TypeError. Replaced with the actual behaviour and the `| slugify | replace("-", "_")` idiom. Also noted that underscores are stripped rather than converted (My_Project -> myproject). 3. Two `default_branch` examples referenced `httpdss/struct`, the old repository name. Also adds the one global missing from the reference (`current_repo()`), documents `to_json`'s `indent` argument, and warns that `uuid()` and `now()` are non-deterministic — a file using either always appears in `generate --dry-run --diff`, which silently ruins that diff as a drift check. --- docs/configuration.md | 14 +++++++++++--- docs/template-variables.md | 37 ++++++++++++++++++++++++++++++++----- 2 files changed, 43 insertions(+), 8 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index b3ec990..8914e4b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -72,7 +72,7 @@ These properties allow you to customize the behavior and content of the files an You can use template variables in your configuration file by enclosing them in `{{@` and `@}}`. For example, `{{@ project_name @}}` will be replaced with the value of the `project_name` variable at runtime. If this are not set when running the script, it will prompt you to enter the value interactively. -If you need to define blocks you can use starting block notation `{%@` and end block notation `%@}`. +If you need to define blocks you can use starting block notation `{%@` and end block notation `@%}`. To define comments you can use the comment start notation `{#@` and end comment notation `@#}`. @@ -141,7 +141,7 @@ You can also use it with Terraform provider repositories, for example `{{@ "hash ##### `slugify` -This filter converts a string into a slug. It takes an optional argument to specify the separator character (default is `-`). +This filter converts a string into a slug. It takes no arguments: the value is lowercased, runs of whitespace become a single hyphen, and any character that is not `a-z`, `0-9`, or `-` is removed. ```yaml files: @@ -152,6 +152,14 @@ files: slugify project_name: {{@ project_name | slugify @}} ``` +Note that underscores are removed rather than converted, so `My_Project` becomes `myproject`. To produce a different separator, chain Jinja2's built-in `replace` filter: + +```yaml +files: + - src/{{@ project_name | slugify | replace("-", "_") @}}/__init__.py: + content: "" +``` + ##### `default_branch` This filter fetches the default branch name of a GitHub repository. It takes the repository name as an argument. @@ -161,5 +169,5 @@ files: - README.md: content: | # MyProject - Default branch: {{@ "httpdss/struct" | default_branch @}} + Default branch: {{@ "httpdss/structkit" | default_branch @}} ``` diff --git a/docs/template-variables.md b/docs/template-variables.md index df5b204..94ad5ff 100644 --- a/docs/template-variables.md +++ b/docs/template-variables.md @@ -29,7 +29,7 @@ files: For control structures, use block notation: - Start block: `{%@` -- End block: `%@}` +- End block: `@%}` ```yaml files: @@ -188,6 +188,12 @@ files: generated_at: {{@ now() @}} ``` +!!! warning "`uuid()` and `now()` are non-deterministic" + A file containing either produces different content on every run, so it always + appears in `structkit generate --dry-run --diff` output. That removes the diff's + value as a drift check. Confine them to files marked `skip_if_exists: true`, or + avoid them in anything you regenerate. + ### `env(name, default="")` (global) Read an environment variable with an optional default. @@ -210,6 +216,19 @@ files: {{@ read_file("INTRO.md") @}} ``` +### `current_repo()` (global) + +Return `owner/repo` for the Git repository in the current working directory, read from +`remote.origin.url`. Both HTTPS and SSH remotes are supported; a non-GitHub remote +returns an error string. + +```yaml +files: + - README.md: + content: | + [![CI](https://github.com/{{@ current_repo() @}}/actions/workflows/ci.yml/badge.svg)](https://github.com/{{@ current_repo() @}}/actions) +``` + ### `to_yaml` / `from_yaml` (filters) Serialize and parse YAML. @@ -228,13 +247,13 @@ files: ### `to_json` / `from_json` (filters) -Serialize and parse JSON. +Serialize and parse JSON. to_json accepts an optional indent argument. ```yaml files: - data.json: content: | - {{@ some_dict | to_json @}} + {{@ some_dict | to_json(indent=2) @}} ``` ```yaml @@ -282,7 +301,15 @@ files: server_name {{@ project_name | slugify @}}; ``` -**Options**: Optional separator character (default: `-`) +**Options**: None. The value is lowercased, runs of whitespace become a single hyphen, and any character that is not `a-z`, `0-9`, or `-` is removed. + +Note that underscores are removed rather than converted, so `My_Project` becomes `myproject`. To produce a different separator, chain Jinja2's built-in `replace` filter: + +```yaml +files: + - src/{{@ project_name | slugify | replace("-", "_") @}}/__init__.py: + content: "" +``` ### `default_branch` @@ -294,7 +321,7 @@ files: content: | on: push: - branches: [ {{@ "httpdss/struct" | default_branch @}} ] + branches: [ {{@ "httpdss/structkit" | default_branch @}} ] ``` ## The `with` Clause