docs: Generate config docs from the pkl by thejcannon · Pull Request #499 · jdx/hk

thejcannon · 2025-12-07T19:51:35Z

This change:

extends bin/generate_docs.rs to now also generate pkl-config.md from Config.pkl
Updates configuration.pkl to just include the newly generated doc
Shifts all the documentation from configuration.md into Config.pkl (as Pkl docstrings)
Fixed a few things up (like adding types to fields missing them)

The result isn't bit-for-bit similar, here's the difference

Some future thoughts:

How to document/handle default values? (Right now we don't use defaultValue, and instead just document the default. This works well for properties with dynamic defaults (e.g. Hook.fix)
The file should be split into multiple .pkl files (just to keep things simple). (Counter-point is pkl files aren't well understood by editors so everything in one file is nice for locality, but meh)
We probably want to split the docs so Configuration is a section header and there's different pages for hk.pkl and hooks and steps.
Put up some linting around the types and default values in Config.pkl (E.g. List<String> = List() vs List<String>?)
- I have a light preference for making (almost) everything nullable, so when we support hk.local.pkl, users can have "reset to the default" semantics by assigning to null
There were some properties that weren't documented, I'll follow up and have us document those

Note

Adds a generator to produce docs/gen/pkl-config.md from pkl/Config.pkl, moves configuration docs into Pkl docstrings, and updates the site to include the generated file.

Docs generation:
- Add generate_pkl_config_doc() in bin/generate_docs.rs to eval/reflect pkl/Config.pkl and emit docs/gen/pkl-config.md.
- Introduce format_property_doc() to render property headings and docstrings.
Pkl reflection:
- Add scripts/reflect.pkl to output class/property metadata (hides output default, exposes annotations).
Config schema/docs:
- Heavily expand pkl/Config.pkl with detailed docstrings, explicit types/defaults, and helpers (Regex, StashMethod).
- Normalize Hook, Step, Group, and testing-related fields; add/clarify properties (e.g., allow_symlinks, output_summary, check_first, etc.).
Site content:
- Replace large manual section in docs/configuration.md with  and keep a concise <GROUP> example and git-status section.
- Continue generating builtins/settings docs; print status lines for new file.

^{Written by Cursor Bugbot for commit 05cdca0. This will update automatically on new commits. Configure here.}

jdx · 2025-12-08T12:58:05Z

bugbot run

bin/generate_docs.rs

jdx · 2025-12-08T14:47:00Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no bugs!

@scop

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [hk](https://github.com/jdx/hk) | minor | `1.26.0` -> `1.27.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>jdx/hk (hk)</summary> ### [`v1.27.0`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1270---2025-12-12) [Compare Source](jdx/hk@v1.26.0...v1.27.0) ##### 🚀 Features - **(lychee)** new builtin by [@scop](https://github.com/scop) in [#510](jdx/hk#510) - **(tombi)** add tombi config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#511](jdx/hk#511) - Apply the step glob to the test files fallback by [@thejcannon](https://github.com/thejcannon) in [#498](jdx/hk#498) - Support `hk.local.pkl` by [@thejcannon](https://github.com/thejcannon) in [#504](jdx/hk#504) - add yamlfmt config to hk builtin config by [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) in [#505](jdx/hk#505) - add `HK_PKL_HTTP_REWRITE` envvar by [@thejcannon](https://github.com/thejcannon) in [#512](jdx/hk#512) ##### 🐛 Bug Fixes - **(builtins)** use `stage = "<JOB_FILES>"` for fix\_smart\_quotes builtin by [@joonas](https://github.com/joonas) in [#503](jdx/hk#503) - add new mise builtin to Builtins.pkl by [@hisaac](https://github.com/hisaac) in [#492](jdx/hk#492) - preserve file permissions in fix-smart-quotes util by [@joonas](https://github.com/joonas) in [#506](jdx/hk#506) ##### 🚜 Refactor - Turn on `taplo-format` by [@thejcannon](https://github.com/thejcannon) in [#501](jdx/hk#501) ##### 📚 Documentation - Generate config docs from the pkl by [@thejcannon](https://github.com/thejcannon) in [#499](jdx/hk#499) ##### 🧪 Testing - Move `ruff` to tool stub and fix up tests by [@thejcannon](https://github.com/thejcannon) in [#487](jdx/hk#487) - Do some test gardening by [@thejcannon](https://github.com/thejcannon) in [#497](jdx/hk#497) - Clean up `test/pkl_config_errors.bats` by [@thejcannon](https://github.com/thejcannon) in [#500](jdx/hk#500) - add yamllint tests by [@thejcannon](https://github.com/thejcannon) in [#509](jdx/hk#509) ##### 📦️ Dependency Updates - update swatinem/rust-cache digest to [`779680d`](jdx/hk@779680d) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#495](jdx/hk#495) - update anthropics/claude-code-action digest to [`6337623`](jdx/hk@6337623) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#494](jdx/hk#494) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#502](jdx/hk#502) ##### New Contributors - [@hituzi-no-sippo](https://github.com/hituzi-no-sippo) made their first contribution in [#511](jdx/hk#511) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

thejcannon added 7 commits December 7, 2025 13:42

generate from pkl

86af881

undo

fd9f220

typo

17948ef

more typos

78e9131

put this back

2d102e3

fix links

5273363

wtf

57dad97

thejcannon mentioned this pull request Dec 7, 2025

WIP: Generate Config docs from Config.pkl #447

Closed

thejcannon changed the title ~~Generate config docs from the pkl~~ docs: Generate config docs from the pkl Dec 7, 2025

cursor bot reviewed Dec 8, 2025

View reviewed changes

bin/generate_docs.rs Outdated Show resolved Hide resolved

rm dead code

05cdca0

cursor bot reviewed Dec 8, 2025

View reviewed changes

jdx merged commit 83ca6e3 into jdx:main Dec 8, 2025
15 checks passed

thejcannon deleted the jcannon/generate-pkl-config branch December 8, 2025 15:20

jdx mentioned this pull request Dec 12, 2025

chore: release v1.27.0 #493

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

docs: Generate config docs from the pkl#499

docs: Generate config docs from the pkl#499
jdx merged 8 commits intojdx:mainfrom
thejcannon:jcannon/generate-pkl-config

thejcannon commented Dec 7, 2025 •

edited by cursor bot

Loading

Uh oh!

jdx commented Dec 8, 2025

Uh oh!

Uh oh!

jdx commented Dec 8, 2025

Uh oh!

cursor bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

thejcannon commented Dec 7, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdx commented Dec 8, 2025

Uh oh!

Uh oh!

jdx commented Dec 8, 2025

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

✅ Bugbot reviewed your changes and found no bugs!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thejcannon commented Dec 7, 2025 •

edited by cursor bot

Loading