Docs site: the Helm chart's, the Kubernetes manifests' and the monitoring READMEs as pages

.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.

.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:

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

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

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)
 

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]

docs/changes/2.2.0/521.docs.md

@@ -0,0 +1,4 @@
+The documentation site, <https://forgepkg.github.io/forge/>, 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.

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<Vec<(String, String)>, 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(&[