docs: Generate `configuration` docs from `settings.toml` in-build by thejcannon · Pull Request #461 · jdx/hk

thejcannon · 2025-11-22T03:59:12Z

This change:

Moves the docs generation from build to bin
Makes it a prereq for docs task

If you think this is a step in the right direction, I'd love to also move the CLI docs to be generated (and so some more docs-gen)

I have a PoC/WIP of generating the rest of the configuration.md docs from Config.pkl here (also planning on doing the builtins)

Alternatives

I first tried to use a "data loader" to load the TOML and Vue templates to render the data. That worked until it was time to render the doc string. You can't have it render Markdown, since Vue is later in the pipeline than Markdown. Womp Womp.

Note

Generates docs/gen/settings-config.md from settings.toml using a new Rust bin, includes it in configuration.md, and wires the generator into docs tasks and CI.

Docs generation:
- Add new bin generate-docs (bin/generate_docs.rs) to produce docs/gen/settings-config.md from settings.toml using shared types in build/settings_toml.rs.
- Replace large inline section in docs/configuration.md with .
- Update docs/.gitignore to ignore gen/.
- Update mise.toml tasks: add docs:gen (runs cargo run --bin generate-docs) and make docs/docs:build depend on it.
Build script refactor:
- Extract settings TOML types to build/settings_toml.rs; update build/mod.rs to expose it.
- Simplify build/generate_settings.rs to import shared types and remove in-build docs generation.
CI (Docs workflow):
- Trigger on settings.toml changes; add Swatinem/rust-cache.
- Build via mise run docs:build; adjust .nojekyll path to docs/.vitepress/dist/.nojekyll.

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

jdx · 2025-11-25T14:05:53Z

Bugbot run

thejcannon · 2025-11-25T17:00:06Z

Excuse me, Bugbot, the man said "run"

jdx · 2025-11-25T17:14:18Z

not sure what I did wrong

jdx · 2025-11-25T17:26:10Z

bugbot run

jdx · 2025-11-25T17:26:38Z

I also think this probably needs some logic for the github action to work right once it's merged to deploy the docs changes

docs/configuration.md

bin/generate_docs.rs

thejcannon · 2025-11-25T19:46:19Z

not sure what I did wrong

Whoops. Bugbot caught the bug. Missing fs::create_dir(_all).

Just fixed it (and tested with rm -rf docs/gen && mise run docs

jdx · 2025-11-26T02:15:56Z

bugbot run

mise.toml

jdx · 2025-11-26T02:57:36Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no bugs!

thejcannon · 2025-11-26T03:04:49Z

Damn, broke the docs build. Was hoping to avoid the submodules. One sec...

thejcannon · 2025-11-26T03:08:51Z

fixing here: #471

@thejcannon

## [1.26.0](https://github.com/jdx/hk/compare/v1.25.0..v1.26.0) - 2025-12-04 ### 🚀 Features - Split `taplo` into `taplo` and `taplo_format` by [@thejcannon](https://github.com/thejcannon) in [#466](#466) - add pkl_format builtin for pkl 0.30 formatter by [@jdx](https://github.com/jdx) in [#475](#475) - add check-conventional-commit utility and built-in by [@joonas](https://github.com/joonas) in [#477](#477) - add mise builtin by [@hisaac](https://github.com/hisaac) in [#480](#480) - forward HTTP proxy env vars to pkl by [@jdx](https://github.com/jdx) in [#486](#486) ### 🐛 Bug Fixes - Fix docs build GHA by [@thejcannon](https://github.com/thejcannon) in [#471](#471) - improve progress bar accuracy for skipped steps and OSC alignment by [@jdx](https://github.com/jdx) in [#472](#472) - cleaner error output for command failures by [@jdx](https://github.com/jdx) in [#474](#474) - update mise builtin glob by [@hisaac](https://github.com/hisaac) in [#482](#482) ### 🚜 Refactor - Remove pointless stage test by [@thejcannon](https://github.com/thejcannon) in [#484](#484) - Move `black` from mise config to tool stub, for testing, and test the builtin by [@thejcannon](https://github.com/thejcannon) in [#483](#483) - Move category/description to annotation by [@thejcannon](https://github.com/thejcannon) in [#485](#485) ### 📚 Documentation - Generate `configuration` docs from `settings.toml` in-build by [@thejcannon](https://github.com/thejcannon) in [#461](#461) - generate builtins docs from Pkl instead of manual sync by [@jdx](https://github.com/jdx) in [#476](#476) ### 🧪 Testing - Stub ktlint and add tests to builtin by [@thejcannon](https://github.com/thejcannon) in [#488](#488) - Bump pkl, fix the builtin, and add tests by [@thejcannon](https://github.com/thejcannon) in [#489](#489) ### 🔍 Other Changes - updated mise lockfile by [@jdx](https://github.com/jdx) in [b10d2e6](b10d2e6) ### 📦️ Dependency Updates - update jdx/mise-action digest to 146a281 by [@renovate[bot]](https://github.com/renovate[bot]) in [#479](#479) - update anthropics/claude-code-action digest to a7e4c51 by [@renovate[bot]](https://github.com/renovate[bot]) in [#478](#478) - lock file maintenance by [@renovate[bot]](https://github.com/renovate[bot]) in [#481](#481) ### New Contributors - @hisaac made their first contribution in [#482](#482)  --- > [!NOTE] > Release v1.26.0 with a new `util check-conventional-commit` command, proxy-forwarding to Pkl, updated docs, and dependency bumps. > > - **Release/Versioning**: > - Bump crate and CLI to `1.26.0`; update all Pkl URLs in examples/templates/docs to `v1.26.0`. > - **CLI/Features**: > - Add `hk util check-conventional-commit` (with `--allowed-types`); expose in usage, KDL spec, commands.json, and docs. > - Add default values to flags in CLI spec/docs (e.g., `config dump --format=json`, migrate defaults, `util --maxkb=500`). > - **Core**: > - Forward HTTP proxy env vars (`http_proxy`, `https_proxy`, `no_proxy`) to Pkl via `--http-proxy/--http-no-proxy` during config parsing. > - **Docs**: > - Regenerate CLI docs (add generated headers) and index; add page for the new util; refresh examples. > - Update CHANGELOG with 1.26.0 entries. > - **Dependencies/Build**: > - Update Cargo.lock (multiple crate version bumps; unify `thiserror` dependency usage). > - Update `mise.lock` entries/checksums. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 2da0194. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  Co-authored-by: mise-en-dev <[email protected]>

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [hk](https://github.com/jdx/hk) | minor | `1.25.0` -> `1.26.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.26.0`](https://github.com/jdx/hk/blob/HEAD/CHANGELOG.md#1260---2025-12-04) [Compare Source](jdx/hk@v1.25.0...v1.26.0) ##### 🚀 Features - Split `taplo` into `taplo` and `taplo_format` by [@thejcannon](https://github.com/thejcannon) in [#466](jdx/hk#466) - add pkl\_format builtin for pkl 0.30 formatter by [@jdx](https://github.com/jdx) in [#475](jdx/hk#475) - add check-conventional-commit utility and built-in by [@joonas](https://github.com/joonas) in [#477](jdx/hk#477) - add mise builtin by [@hisaac](https://github.com/hisaac) in [#480](jdx/hk#480) - forward HTTP proxy env vars to pkl by [@jdx](https://github.com/jdx) in [#486](jdx/hk#486) ##### 🐛 Bug Fixes - Fix docs build GHA by [@thejcannon](https://github.com/thejcannon) in [#471](jdx/hk#471) - improve progress bar accuracy for skipped steps and OSC alignment by [@jdx](https://github.com/jdx) in [#472](jdx/hk#472) - cleaner error output for command failures by [@jdx](https://github.com/jdx) in [#474](jdx/hk#474) - update mise builtin glob by [@hisaac](https://github.com/hisaac) in [#482](jdx/hk#482) ##### 🚜 Refactor - Remove pointless stage test by [@thejcannon](https://github.com/thejcannon) in [#484](jdx/hk#484) - Move `black` from mise config to tool stub, for testing, and test the builtin by [@thejcannon](https://github.com/thejcannon) in [#483](jdx/hk#483) - Move category/description to annotation by [@thejcannon](https://github.com/thejcannon) in [#485](jdx/hk#485) ##### 📚 Documentation - Generate `configuration` docs from `settings.toml` in-build by [@thejcannon](https://github.com/thejcannon) in [#461](jdx/hk#461) - generate builtins docs from Pkl instead of manual sync by [@jdx](https://github.com/jdx) in [#476](jdx/hk#476) ##### 🧪 Testing - Stub ktlint and add tests to builtin by [@thejcannon](https://github.com/thejcannon) in [#488](jdx/hk#488) - Bump pkl, fix the builtin, and add tests by [@thejcannon](https://github.com/thejcannon) in [#489](jdx/hk#489) ##### 🔍 Other Changes - updated mise lockfile by [@jdx](https://github.com/jdx) in [b10d2e6](jdx/hk@b10d2e6) ##### 📦️ Dependency Updates - update jdx/mise-action digest to [`146a281`](jdx/hk@146a281) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#479](jdx/hk#479) - update anthropics/claude-code-action digest to [`a7e4c51`](jdx/hk@a7e4c51) by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#478](jdx/hk#478) - lock file maintenance by [@renovate\[bot\]](https://github.com/renovate\[bot]) in [#481](jdx/hk#481) ##### New Contributors - [@hisaac](https://github.com/hisaac) made their first contribution in [#482](jdx/hk#482) </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).

merge main

d7e43c9

thejcannon force-pushed the jcannon/gen-docs-from-settings branch from 2612a79 to d7e43c9 Compare November 23, 2025 02:10

thejcannon added 2 commits November 22, 2025 20:21

rename

d6a03ff

dead import

be0484b

thejcannon marked this pull request as ready for review November 23, 2025 02:33

thejcannon added 3 commits November 24, 2025 20:24

add missing include

009b2e7

tweaks

81f52ed

omg

0ef75ee

cursor bot reviewed Nov 25, 2025

View reviewed changes

docs/configuration.md Outdated Show resolved Hide resolved

bin/generate_docs.rs Show resolved Hide resolved

fix a few whoopsies

5e75956

cursor bot reviewed Nov 26, 2025

View reviewed changes

mise.toml Show resolved Hide resolved

make docs build work

f53d2a2

cursor bot reviewed Nov 26, 2025

View reviewed changes

jdx merged commit 15dc620 into jdx:main Nov 26, 2025
15 checks passed

thejcannon deleted the jcannon/gen-docs-from-settings branch November 26, 2025 03:04

jdx mentioned this pull request Nov 26, 2025

chore: release v1.26.0 #470

Merged

Comments

Conversation

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

Uh oh!

Alternatives

Uh oh!

jdx commented Nov 25, 2025

Uh oh!

thejcannon commented Nov 25, 2025

Uh oh!

jdx commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdx commented Nov 25, 2025

Uh oh!

jdx commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thejcannon commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdx commented Nov 26, 2025

Uh oh!

Uh oh!

jdx commented Nov 26, 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!

thejcannon commented Nov 26, 2025

Uh oh!

thejcannon commented Nov 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thejcannon commented Nov 22, 2025 •

edited by cursor bot

Loading

jdx commented Nov 25, 2025 •

edited

Loading

jdx commented Nov 25, 2025 •

edited

Loading

thejcannon commented Nov 25, 2025 •

edited

Loading