Skip to content

Comments

WIP: Generate Config docs from Config.pkl#447

Closed
thejcannon wants to merge 1 commit intojdx:mainfrom
thejcannon:jcannon/generate-config
Closed

WIP: Generate Config docs from Config.pkl#447
thejcannon wants to merge 1 commit intojdx:mainfrom
thejcannon:jcannon/generate-config

Conversation

@thejcannon
Copy link
Contributor

@thejcannon thejcannon commented Nov 20, 2025

PKL has reflection: https://pkl-lang.org/package-docs/pkl/0.30.0/reflect/index.html

So I think it'd be pretty sweet to see if we can single-source the info from the config. This PR is a WIP for that.

  • To get the reflected output: pkl eval pkl/Config.pkl -m <dir> --format <format

@thejcannon thejcannon force-pushed the jcannon/generate-config branch from 3690933 to 576c294 Compare November 20, 2025 15:29
@thejcannon
Copy link
Contributor Author

JK: pkl eval pkl/Config.pkl -x 'module.output.renderer.renderDocument(import("pkl:reflect").Module(module))' --format json

@thejcannon thejcannon force-pushed the jcannon/generate-config branch from faaa8ca to 0f42b88 Compare November 24, 2025 14:56
jdx pushed a commit that referenced this pull request Nov 26, 2025
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](#447) (also
planning on doing the `builtins`)

# Alternatives

I first tried to use a ["data
loader"](https://vitepress.dev/guide/data-loading#basic-usage) 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.

<!-- CURSOR_SUMMARY -->
---

> [!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
`<!--@include: ./gen/settings-config.md-->`.
>   - 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`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
f53d2a2. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
@thejcannon thejcannon force-pushed the jcannon/generate-config branch from 5526b41 to 86c2c51 Compare December 2, 2025 02:33
@thejcannon
Copy link
Contributor Author

#499

@thejcannon thejcannon closed this Dec 7, 2025
@thejcannon thejcannon deleted the jcannon/generate-config branch December 7, 2025 20:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant