WIP: Generate Config docs from Config.pkl#447
Closed
thejcannon wants to merge 1 commit intojdx:mainfrom
Closed
Conversation
3690933 to
576c294
Compare
Contributor
Author
|
JK: |
faaa8ca to
0f42b88
Compare
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 -->
5526b41 to
86c2c51
Compare
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
pkl eval pkl/Config.pkl -m <dir> --format <format