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(&[