From 04b3fd34679b6fb2944c34f2cdafb48c580525c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 22:06:12 +0000 Subject: [PATCH] Docs site: the Helm chart's, the Kubernetes manifests' and the monitoring READMEs as pages The site built from docs/SUMMARY.md left out the guides under deploy/: a link to them went to the file on GitHub. SUMMARY.md and docs/README.md now list them under Running Forge, and the staging names a README other than the repository's after its directory (deploy-helm-forge.md, deploy-kubernetes.md, deploy-monitoring.md), so the site stays flat and their links resolve from it. CI's fmt job checks the links for a change to deploy/, whose files the READMEs link, and the Pages workflow deploys a change to them. Fixes #521 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012e6DJbEWF3MPtSyVBYSt2r --- .github/scripts/ci-changes.sh | 5 +-- .github/workflows/pages.yml | 1 + DEVELOPMENT.md | 23 ++++++++------ docs/README.md | 7 ++++ docs/SUMMARY.md | 3 ++ docs/book.toml | 5 +-- docs/changes/2.2.0/521.docs.md | 4 +++ xtask/src/docs.rs | 58 ++++++++++++++++++++++++++++++---- 8 files changed, 87 insertions(+), 19 deletions(-) create mode 100644 docs/changes/2.2.0/521.docs.md diff --git a/.github/scripts/ci-changes.sh b/.github/scripts/ci-changes.sh index c5dd349a..6dc3ff40 100755 --- a/.github/scripts/ci-changes.sh +++ b/.github/scripts/ci-changes.sh @@ -58,8 +58,9 @@ RUST=( .github/scripts/raw-e2e.sh .github/scripts/npm-e2e.sh ) # fmt's other checks: the changelog fragments, and the links of the -# documentation site's pages (the README, docs/ and the changelog). -CHANGELOG=(docs README.md CHANGELOG.md) +# documentation site's pages (the README, docs/, the READMEs under deploy/ and +# the changelog). All of deploy/, since those READMEs link its files. +CHANGELOG=(docs README.md CHANGELOG.md deploy) # What xtask's tests, which fmt runs too (#363), read from outside xtask: the # version lines `cargo xtask release` sets, and the release workflow's channel # script. diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 61bb0f4b..2d724aaf 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -13,6 +13,7 @@ on: - README.md - CHANGELOG.md - docs/** + - deploy/**/README.md - xtask/src/docs.rs - .github/workflows/pages.yml pull_request: diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 04db39f3..6a854101 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1087,7 +1087,9 @@ next milestone. The guides are also a site, https://forgepkg.github.io/forge/, built with [mdBook](https://rust-lang.github.io/mdBook/) from the pages [docs/SUMMARY.md](docs/SUMMARY.md) lists: the README (the start page), the -guides in `docs/` and the changelog. `docs/book.toml` configures it. +guides in `docs/`, the READMEs of the Helm chart, the Kubernetes manifests +and the monitoring examples under `deploy/`, and the changelog. +`docs/book.toml` configures it. ```bash cargo install mdbook --version 0.5.4 --locked @@ -1099,14 +1101,17 @@ site into `target/docs/book`; open `target/docs/book/index.html`. The pages keep linking each other and the source tree relatively, as GitHub shows them. The staging rewrites a link to another page into that page of the site, and a link into the source tree (`../crates/…`) into the file on -GitHub, on `main`. It fails on a link to a file or heading that does not -exist, and on a Markdown file directly in `docs/` that SUMMARY.md does not -list: a new guide goes into SUMMARY.md, under its part, and into -[docs/README.md](docs/README.md), the index GitHub shows for the folder. That -index is no page of the site, but its links are checked as a page's, and the -staging fails when it does not link a page SUMMARY.md lists. `cargo xtask docs ---check` runs the staging without mdBook; CI's `fmt` job runs it for a change -to the pages or to the Rust code, whose files the pages link. +GitHub, on `main`. A README other than the repository's is named after its +directory on the site: `deploy/kubernetes/README.md` is +`deploy-kubernetes.html`. The staging fails on a link to a file or heading +that does not exist, and on a Markdown file directly in `docs/` that +SUMMARY.md does not list: a new guide goes into SUMMARY.md, under its part, +and into [docs/README.md](docs/README.md), the index GitHub shows for the +folder. That index is no page of the site, but its links are checked as a +page's, and the staging fails when it does not link a page SUMMARY.md +lists. `cargo xtask docs --check` runs the staging without mdBook; CI's +`fmt` job runs it for a change to the pages, to `deploy/` or to the Rust +code, whose files the pages link. The Pages workflow (`.github/workflows/pages.yml`) deploys the site when a push to `main` changes a page, and builds it for a pull request that changes diff --git a/docs/README.md b/docs/README.md index d66be0d5..f97bd1bc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,13 @@ its [quickstart](../README.md#quickstart); - **[Production deployment](deployment.md)**: required settings, TLS and the reverse proxy, secret encryption, health probes, backup and restore, and upgrades. +- **[Helm chart](../deploy/helm/forge/README.md)**: the chart published with + every release: which image it runs, its values, short-lived S3 + credentials, routing, optional dependencies and telemetry. +- **[Kubernetes manifests](../deploy/kubernetes/README.md)**: the kustomize + base, components and overlays, for production and for an evaluation. +- **[Monitoring](../deploy/monitoring/README.md)**: an example OpenTelemetry + Collector configuration, Grafana dashboard and Prometheus alerting rules. - **[Retention size budgets](retention.md)**: keep a repository under a logical size: the budget, how size is counted, and what goes first. - **[Importing from Nexus](nexus-import.md)**: copy a Nexus hosted repository diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 9392d1ed..4b18c800 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -5,6 +5,9 @@ # Running Forge - [Production deployment](deployment.md) +- [Helm chart](../deploy/helm/forge/README.md) +- [Kubernetes manifests](../deploy/kubernetes/README.md) +- [Monitoring](../deploy/monitoring/README.md) - [Retention size budgets](retention.md) - [Importing from Nexus](nexus-import.md) diff --git a/docs/book.toml b/docs/book.toml index a43a746b..c6f4bd28 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -1,8 +1,9 @@ # The documentation site, https://forgepkg.github.io/forge/. # # `cargo xtask docs` stages the pages SUMMARY.md lists (the README, the guides -# in this directory and the changelog) into target/docs/src, with their links -# rewritten for the site, and builds them with mdBook into target/docs/book. +# in this directory, the READMEs under deploy/ and the changelog) into +# target/docs/src, with their links rewritten for the site, and builds them +# with mdBook into target/docs/book. # The Pages workflow (.github/workflows/pages.yml) publishes the build of main. [book] diff --git a/docs/changes/2.2.0/521.docs.md b/docs/changes/2.2.0/521.docs.md new file mode 100644 index 00000000..d201e972 --- /dev/null +++ b/docs/changes/2.2.0/521.docs.md @@ -0,0 +1,4 @@ +The documentation site, , has the guides +of the Helm chart, the Kubernetes manifests and the monitoring examples as +pages under **Running Forge**, next to the deployment guide; they were only +READMEs under `deploy/` on GitHub. diff --git a/xtask/src/docs.rs b/xtask/src/docs.rs index 23055aa7..79862928 100644 --- a/xtask/src/docs.rs +++ b/xtask/src/docs.rs @@ -1,10 +1,11 @@ //! The documentation site, and `cargo xtask docs`. //! //! The site is an mdBook ([`BOOK_TOML`]) of the pages [`SUMMARY`] lists, in -//! its order: the README (the start page), the guides under `docs/` and the -//! changelog. The pages link each other and the source tree relatively, as -//! GitHub shows the repository, so the site is built from a copy staged in -//! [`STAGE`] whose links work there: +//! its order: the README (the start page), the guides under `docs/`, the +//! READMEs of the Helm chart, the Kubernetes manifests and the monitoring +//! examples under `deploy/`, and the changelog. The pages link each other and +//! the source tree relatively, as GitHub shows the repository, so the site is +//! built from a copy staged in [`STAGE`] whose links work there: //! //! * a link to another page goes to that page of the site; //! * a link into the source tree (`../crates/…`, `../DEVELOPMENT.md`) goes to @@ -236,12 +237,18 @@ fn stage(tree: &impl Tree, repo: &str) -> Result, String> } } -/// A page's name on the site: the README is the start page, every other -/// page keeps its file name, in lower case (`CHANGELOG.md` → `changelog.md`). +/// A page's name on the site: the README is the start page, the README of a +/// directory is named after the directory's path (`deploy/kubernetes/README.md` +/// → `deploy-kubernetes.md`), and every other page keeps its file name, in +/// lower case (`CHANGELOG.md` → `changelog.md`). The site is flat, since a +/// page's links name the other pages from the site's root. fn site_name(path: &str) -> String { if path == "README.md" { return "index.md".into(); } + if let Some(dir) = path.strip_suffix("/README.md") { + return format!("{}.md", dir.replace('/', "-").to_lowercase()); + } path.rsplit('/').next().unwrap_or(path).to_lowercase() } @@ -654,6 +661,45 @@ mod tests { ); } + #[test] + fn a_directory_readme_is_named_after_its_directory() { + let tree = repo(&[ + ( + "docs/SUMMARY.md", + "- [Guide](guide.md)\n- [Chart](../deploy/helm/x/README.md)\n", + ), + ( + "docs/guide.md", + "# Guide\n\nInstall [the chart](../deploy/helm/x/README.md#values).\n", + ), + ( + "deploy/helm/x/README.md", + "# Chart\n\n## Values\n\nSee [values](values.yaml), [the guide](../../../docs/guide.md) \ + and [the templates](templates).\n", + ), + ("deploy/helm/x/values.yaml", ""), + ("deploy/helm/x/templates/a.yaml", ""), + ]); + let files = stage(&tree, REPO).expect("stages"); + let names: Vec<_> = files.iter().map(|(n, _)| n.as_str()).collect(); + assert_eq!(names, ["guide.md", "deploy-helm-x.md", "SUMMARY.md"]); + assert_eq!( + page(&files, "guide.md"), + "# Guide\n\nInstall [the chart](deploy-helm-x.md#values).\n" + ); + assert_eq!( + page(&files, "deploy-helm-x.md"), + "# Chart\n\n## Values\n\n\ + See [values](https://github.com/o/r/blob/main/deploy/helm/x/values.yaml), \ + [the guide](guide.md) \ + and [the templates](https://github.com/o/r/tree/main/deploy/helm/x/templates).\n" + ); + assert_eq!( + page(&files, "SUMMARY.md"), + "- [Guide](guide.md)\n- [Chart](deploy-helm-x.md)\n" + ); + } + #[test] fn broken_links_and_unlisted_pages_fail() { let tree = repo(&[