diff --git a/crates/schemars-docgen/README.md b/crates/schemars-docgen/README.md new file mode 100644 index 00000000..e9a7e77e --- /dev/null +++ b/crates/schemars-docgen/README.md @@ -0,0 +1,23 @@ +# schemars-docgen + +Writes the reference pages of the docs site (`starlight/`) from a JSON Schema made by `schemars`: one MDX page with +every type, property, default and enum variant of `schemas//schema.json` or `schema.bar.json`, with links +between the types. + +It is a development tool: no release ships it, and it is not a default member of the workspace, so a bare +`cargo build` leaves it out. Run it from the tree: + +```sh +just docgen # on Windows or macOS: the schema pages, the command pages and the komorebic page, into starlight/ +``` + +or by hand, for one schema: + +```sh +cargo run -p schemars-docgen -- schemas/macos/schema.json --output page.mdx --title "komorebi.json" --description "..." +``` + +`ENUMS.md` is the analysis of how `schemars` writes each shape of Rust enum into a schema, which is what the tool +turns back into text. + +`nix build .#schemars-docgen` builds it, and `nix build .#checkSets.docgen-lint .#checkSets.docgen-test` check it. diff --git a/docs/dev/ARCHITECTURE-UNIFIED.md b/docs/dev/ARCHITECTURE-UNIFIED.md index 7221aaec..248eaedc 100644 --- a/docs/dev/ARCHITECTURE-UNIFIED.md +++ b/docs/dev/ARCHITECTURE-UNIFIED.md @@ -24,7 +24,7 @@ The root `Cargo.toml` is the only workspace. One rule says where a member lives: the `komorebi` binary; - every **library** and every **development tool** lives under `crates//`: the daemon libraries of the three platforms, the shared crates, the end-to-end guests (`crates/komorebi-e2e-agent`, - `crates/komorebi-testwin`) and `crates/schemars-nixgen`. + `crates/komorebi-testwin`), `crates/schemars-nixgen` and `crates/schemars-docgen`. The platform-specific parts are: @@ -36,7 +36,8 @@ The platform-specific parts are: Shared: `crates/` (the libraries; including `crates/komorebi-version`, the version string of the Linux and macOS binaries), `schemas/{windows,linux,macos}/` (the generated JSON schemas), one `deny.toml`, `rustfmt.toml`, -`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root. The old repositories' +`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root; `starlight/` (the docs site, an Astro +Starlight project whose reference pages `just docgen` writes with `crates/schemars-docgen`). The old repositories' workflows, dependabot files, the Homebrew formula template and the macOS docs-site files are kept, inert, in `docs/dev/old-ci/{linux,macos}/` for the CI and release plan. There is no `komorebi-for-kde/` or `komorebi-for-mac/` any more except the two flakes that `flake-one` is replacing. diff --git a/docs/dev/CUTOVER-PLAN.md b/docs/dev/CUTOVER-PLAN.md index 2b9e3ea7..640a6a7f 100644 --- a/docs/dev/CUTOVER-PLAN.md +++ b/docs/dev/CUTOVER-PLAN.md @@ -359,7 +359,7 @@ from `master` see the new tree (1.4). **Release:** a revision on `master` that s | Linux (KDE) | zip of `komorebi`, `komorebic` for x86_64 and aarch64 (patchelf'ed to the system glibc loader, as the old `build` job did), `schema.json`; the **NixOS module** and overlay through the flake; no tarball existed | nix (native `komorebi`, `komorebic`), `ubuntu-24.04` and `ubuntu-24.04-arm` | `komorebi--x86_64-unknown-linux-gnu.zip` | | macOS aarch64 | zip of `komorebi`, `komorebic`, `komorebi-bar` (nix `result/bin/*`), `checksums.txt`, Homebrew formula, the nix-darwin module through the flake | nix on a Mac (native `komorebi`, `komorebic`, `komorebi-bar`) | `komorebi--aarch64-apple-darwin.zip` (no leading `v`: the old release.yaml included it, `komorebi-v0.1.1-...`; choose the Windows form) | | Schemas | `schemas/{windows,linux,macos}/schema*.json` attached to the release and published to the schema host | `just schemapub` (Cloudflare Pages `komorebi`, copies `schemas//`) | per-platform files in the repository (decided); the published names are the open part of R5 | -| Docs | **Starlight for all three platforms** (owner, R3); `gh-pages` (MkDocs, `mkdocs gh-deploy`: the last commit on `gh-pages` is "Deployed 8f982e45 with MkDocs version 1.6.1", i.e. a manual deploy) is deprecated: steps in 4.9. The Starlight reference by `just docgen starlight ` | by hand | root `mkdocs.yml` keeps `exclude_docs` `/linux/`, `/macos/`, `/dev/` (commit `4eae178f`) only while MkDocs still builds anything (4.9) | +| Docs | **Starlight for all three platforms** (owner, R3); `gh-pages` (MkDocs, `mkdocs gh-deploy`: the last commit on `gh-pages` is "Deployed 8f982e45 with MkDocs version 1.6.1", i.e. a manual deploy) is deprecated: steps in 4.9. The Starlight reference by `just docgen` (into `starlight/`) | by hand | root `mkdocs.yml` keeps `exclude_docs` `/linux/`, `/macos/`, `/dev/` (commit `4eae178f`) only while MkDocs still builds anything (4.9) | `crates.io`: no crate is published today as far as the repository says; do not start with 0.2.0. @@ -395,7 +395,7 @@ What must change: (a) **one `nightly` release for the whole repository**: the Wi ### 4.9 Retiring the `gh-pages` site (R3: Starlight for all docs; gh-pages deprecated) -Facts: Pages serves branch `gh-pages` at `https://lgug2z.github.io/komorebi/` (`gh api repos/LGUG2Z/komorebi/pages`); the branch is a manual `mkdocs gh-deploy` result; the old site is linked from `README.md`, `komorebic/src/windows.rs` and `komorebic/src/macos/mod.rs` (help text), `.github/ISSUE_TEMPLATE/config.yml` and `bug_report.yml`, and from every installed 0.1.x binary's help. Where the guide pages (installation, usage, common-workflows) are the source of truth after the move, in this repository's `docs/` or in the `komorebi-starlight` repository: **(unknown)**; `just docgen starlight` only generates the CLI pages and schema reference pages into Starlight. +Facts: Pages serves branch `gh-pages` at `https://lgug2z.github.io/komorebi/` (`gh api repos/LGUG2Z/komorebi/pages`); the branch is a manual `mkdocs gh-deploy` result; the old site is linked from `README.md`, `komorebic/src/windows.rs` and `komorebic/src/macos/mod.rs` (help text), `.github/ISSUE_TEMPLATE/config.yml` and `bug_report.yml`, and from every installed 0.1.x binary's help. Where the guide pages (installation, usage, common-workflows) are the source of truth after the move, in this repository's `docs/` or in the Starlight site: **(unknown)**; the site is `starlight/` in this repository now (the `komorebi-starlight` history is merged in), and `just docgen` only generates the CLI pages and schema reference pages into it. Steps (owner): 1. Starlight has the guides of all three platforms (Windows from `docs/`, Linux from `docs/linux/`, macOS from `docs/macos/`) and its build passes. 2. Retarget the links above (and the `$schema`/docs links of 2.3 class F) to the Starlight address. 3. Replace the `gh-pages` content by a one-page redirect to Starlight and leave it for a period the owner chooses (old binaries and bookmarks still point to it), then disable Pages in the settings, then delete the branch last (back it up as a tag first; deleting is the only irreversible part). 4. **`mkdocs.yml` and the Windows docs source:** while MkDocs builds anything, the root `mkdocs.yml` keeps `exclude_docs` for `/linux/`, `/macos/` and `/dev/` (commit `4eae178f`) so a MkDocs build still excludes the other platforms' pages; when the last MkDocs build is gone, delete `mkdocs.yml`, `check_schema_docs.py` if it only serves it (check first), and decide whether the Windows Markdown under `docs/` stays as in-repo documentation (recommended: keep it, it is what `komorebic` and README link to and what Starlight can import) or moves wholly into Starlight. ## 5. Sequencing and gates diff --git a/docs/dev/build-and-test.md b/docs/dev/build-and-test.md index 39aa0a2d..b9066f3c 100644 --- a/docs/dev/build-and-test.md +++ b/docs/dev/build-and-test.md @@ -180,6 +180,22 @@ Nix, on a Mac: the `macos-*` checks (`macos-{clippy,fmt,toml-fmt,deny,nextest}`, `komorebi-bar` of `aarch64-darwin`. From Linux they can be evaluated only (`nix flake check --no-build --all-systems`, `nix eval`), which proves nothing builds. +## The docs site (`starlight/`) + +The site is an Astro Starlight project, with the pages of Windows and macOS. The guides are written by hand in +`starlight/src/content/docs/`; the reference is generated, and `just docgen` on Windows or macOS writes it in its +final form into the same directory (`komorebic-.mdx`, `komorebi-.mdx`, `bar-.mdx`, and +the page of every command in `starlight/src/data/cli//`). Run it again after a change of a command, of its +help or of `schemas//`; it needs `node` (in the dev shell) and builds `komorebic` and `schemars-docgen`. + +```sh +just docgen # the reference pages of this platform +cd starlight && npm ci && npm run dev # the site on localhost; `npm run build` makes dist/ +``` + +`ci / starlight` runs `npm ci` and `npm run build` when a file of `starlight/` changes. `nix build +.#checkSets.docgen-lint .#checkSets.docgen-test` checks the tool. + ## 4. Windows e2e (QEMU guest) Full text: `e2e/platforms/qemu_windows/README.md` (building the golden image, every variable). Short form: diff --git a/starlight/README.md b/starlight/README.md index 34fd3bf9..82f5a2f6 100644 --- a/starlight/README.md +++ b/starlight/README.md @@ -1,4 +1,15 @@ -# komorebi-starlight +# starlight -Experimental unified documentation site for komorebi for Windows and macOS built -with Starlight. +The documentation site of komorebi, for Windows and macOS, built with [Starlight](https://starlight.astro.build). + +```sh +npm ci +npm run dev # the site on localhost, after generating the komorebic pages +npm run build # dist/, which `wrangler.jsonc` deploys +``` + +The guides are written by hand in `src/content/docs/`. The reference pages (`src/content/docs/reference/` and +`src/data/cli/`) are generated: run `just docgen` from the root of the repository on Windows or macOS after a change +of a command or of a schema, and commit what it writes. It writes the page of the platform it runs on, so the +pages of the other one stay as they are. `komorebic-.mdx` is made by `scripts/generate-cli-reference.cjs` +from the pages of the commands and is not committed (`npm run dev` and `npm run build` make it too).