docs: Ship canonical website chapters as installed manuals - #2508
Open
HarshwardhanPatil07 wants to merge 8 commits into
Open
HarshwardhanPatil07 wants to merge 8 commits into
HarshwardhanPatil07 wants to merge 8 commits into
Conversation
Set manual headers from filenames, keep temporary inputs in target/man, and regenerate when version metadata changes. Escape leading apostrophes so roff does not silently drop prose. Add regression tests for headers, apostrophes, and boolean options. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Map narrative chapters to stable section 7 names and validate one-to-one coverage with SUMMARY.md. Keep existing navigation flat while exposing the previously unlisted command references. Reject missing, duplicate, empty, and unsafe entries before rendering. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Use parsed Markdown spans to preserve formatting and code examples while mapping chapter links to installed manuals. Keep external links intact and resolve generated web artifacts against bootc.dev. Reject missing or escaping local documentation links. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Convert supported Mermaid flowcharts and two-column guide tables using parsed Markdown spans, leaving fenced examples untouched. Reject unsupported diagram syntax rather than silently losing it. Wrap long command examples for terminal reading. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Render canonical narrative chapters into section 7 without creating Markdown copies. Generate bootc-docs(7) in website navigation order, include manual cross-references and version metadata, and remove stale generated guide output. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Install section 7 alongside sections 5 and 8, fail the install target if generation fails, and validate coverage during website and generated-file checks. Route reference generation through the shared inventory and point bootc(8) at the offline index. The existing RPM man* file glob already covers the new manuals. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
Keep each shared explanation in one canonical source so website and installed manuals cannot drift through separately maintained copies. Keep installation configuration discovery and merge precedence in its reference manual, and soft-reboot behavior in the upgrades guide. Replace repeated explanations with links while retaining command-specific details. Align the canonical text and CLI help with the implemented behavior, including platform-specific bootloader setup and the experimental composefs soft-reboot fallback limitation. No runtime behavior changes. Assisted-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
HarshwardhanPatil07
force-pushed
the
docs/base-image-manpage-pipeline
branch
from
September 28, 2026 07:17
f8ac56b to
00fdf36
Compare
Keep one naming convention for guides and reference manuals instead of maintaining a separate chapter-to-manual manifest. Rename narrative chapters to stable section-7 filenames, reuse filename parsing, and update links without changing prose or navigation. Preserve published website URLs with mdBook redirects. Generated-by: AI Signed-off-by: HarshwardhanPatil07 <harshpat@redhat.com>
HarshwardhanPatil07
force-pushed
the
docs/base-image-manpage-pipeline
branch
from
September 28, 2026 10:25
10ce981 to
0f2f55b
Compare
HarshwardhanPatil07
marked this pull request as ready for review
September 28, 2026 10:30
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The redirect configuration is invalid for the pinned mdBook version, and several new manuals document unsupported names or options.
Review effort: Balanced
Findings: 1
Open (2)
What changed in this PR
Unifies website chapters and installed manuals around canonical Markdown sources, generating 72 manuals from the mdBook inventory.
Changes:
- Renames and relinks canonical documentation as section 7 manuals.
- Adds shared validation, link rewriting, and man-page generation.
- Installs section 7 manuals through the existing RPM path.
| File | Description |
|---|---|
Makefile |
Installs section 7 manuals. |
docs/src/SUMMARY.md |
Updates canonical navigation paths. |
docs/src/man/bootc.8.md |
Links the documentation index. |
docs/src/man/bootc-upgrade.8.md |
Deduplicates soft-reboot guidance. |
docs/src/man/bootc-switch.8.md |
Deduplicates soft-reboot guidance. |
docs/src/man/bootc-install.8.md |
Links installation guidance. |
docs/src/man/bootc-install-to-existing-root.8.md |
Updates a renamed link. |
docs/src/man/bootc-install-config.5.md |
Expands configuration precedence documentation. |
docs/src/building/bootc-users-and-groups.7.md |
Updates a renamed link. |
docs/src/building/bootc-secrets.7.md |
Reformats an example. |
docs/src/building/bootc-management-services.7.md |
Reformats an example. |
docs/src/building/bootc-kernel-arguments.7.md |
Provides kernel-argument guidance. |
docs/src/building/bootc-dns.7.md |
Updates renamed links. |
docs/src/building/bootc-container-runtime.7.md |
Updates renamed links. |
docs/src/building/bootc-building-images.7.md |
Updates renamed links. |
docs/src/bootc-upgrades.7.md |
Centralizes soft-reboot behavior. |
docs/src/bootc-systemd-particles.7.md |
Provides systemd-particles guidance. |
docs/src/bootc-sysroot.7.md |
Updates renamed links. |
docs/src/bootc-security.7.md |
Provides security guidance. |
docs/src/bootc-relationships.7.md |
Updates a renamed link. |
docs/src/bootc-registries-and-offline.7.md |
Provides registry and offline guidance. |
docs/src/bootc-packaging-and-integration.7.md |
Updates a renamed link. |
docs/src/bootc-package-managers.7.md |
Updates links and formatting. |
docs/src/bootc-overview.7.md |
Provides the introductory manual. |
docs/src/bootc-oci-artifacts.7.md |
Documents OCI artifact relationships. |
docs/src/bootc-logically-bound-images.7.md |
Updates links and formatting. |
docs/src/bootc-local-builds.7.md |
Documents local image builds. |
docs/src/bootc-internals.7.md |
Updates a renamed link. |
docs/src/bootc-installation.7.md |
Updates installation guidance and links. |
docs/src/bootc-initramfs.7.md |
Updates renamed links. |
docs/src/bootc-in-container.7.md |
Documents container behavior. |
docs/src/bootc-filesystem.7.md |
Updates canonical cross-references. |
docs/src/bootc-filesystem-encryption.7.md |
Updates a renamed link. |
docs/src/bootc-experimental-unified-storage.7.md |
Updates renamed links. |
docs/src/bootc-experimental-progress-fd.7.md |
Documents progress output. |
docs/src/bootc-experimental-install-reset.7.md |
Documents factory reset. |
docs/src/bootc-experimental-image.7.md |
Updates a renamed link. |
docs/src/bootc-experimental-fsck.7.md |
Documents experimental fsck. |
docs/src/bootc-experimental-container-export.7.md |
Documents container export. |
docs/src/bootc-experimental-composefs.7.md |
Updates canonical links. |
docs/src/bootc-container-storage.7.md |
Updates canonical links. |
docs/src/bootc-compatible-images.7.md |
Updates the bootloader link. |
docs/src/bootc-bootloaders.7.md |
Provides bootloader guidance. |
docs/src/bootc-boot-failure-detection.7.md |
Documents failure detection. |
docs/src/bootc-base-images.7.md |
Updates a renamed link. |
docs/src/bootc-api.7.md |
Documents API usage. |
docs/Dockerfile.mdbook |
Validates sources before mdBook. |
docs/book.toml |
Defines legacy URL redirects. |
crates/xtask/src/xtask.rs |
Adds guide generation and validation commands. |
crates/xtask/src/man/guides.rs |
Adapts guides for terminal output. |
crates/xtask/src/man.rs |
Implements shared inventory and generation. |
crates/xtask/Cargo.toml |
Adds Markdown parsing support. |
crates/lib/src/cli.rs |
Clarifies soft-reboot help. |
CONTRIBUTING.md |
Updates a documentation link. |
Cargo.lock |
Locks the new parser dependency. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+21
to
+22
| [output.html.redirect] | ||
| "boot-failure-detection.html" = "bootc-boot-failure-detection.7.html" |
| the file in the later directory in this list takes precedence. The selected | ||
| files are then processed in alphanumerical filename order. | ||
|
|
||
| Fragments whose `match_architectures` includes the current architecture, or |
cgwalters
approved these changes
Sep 28, 2026
cgwalters
left a comment
cgwalters
left a comment
Collaborator
There was a problem hiding this comment.
Overall LGTM but I think there's some longer term/harder work around basically cleaning up our docs to feel more man-page like right?
I think we have some tech debt in documentation duplication; e.g. the install stuff.
The mermaid is just one example.
| Ok(result) | ||
| } | ||
|
|
||
| fn flowchart_as_text(diagram: &str) -> Result<String> { |
Collaborator
There was a problem hiding this comment.
Couldn't we have mermaid render to ASCII art? To investigate.
This branch has not been deployed
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.
Purpose
Ship the same canonical documentation on the bootc website and as man pages through the existing RPM packaging path, without maintaining duplicate documentation.
Narrative chapters remain under
docs/src, renamed to<manual-name>.7.md. Manual names and sections are derived directly from filenames; nodocs/manpages.tomlmapping is required. Existing section 5 and 8 references remain underdocs/src/man, including their generated CLI-option blocks.SUMMARY.mdremains the navigation source. Existing labels, grouping, and order are preserved, without duplicate website chapters or additional nested navigation. Redirects preserve the previous website URLs.Generation is shared in man.rs; guides.rs contains only guide-specific formatting and terminal adaptations.
The inventory contains 71 canonical pages: 38 guides and 33 references. Generation produces 72 manuals. The Makefile installs sections 5, 7, and 8 through the existing RPM build/install path. The spec’s existing
%{_mandir}/man*/*bootc*pattern covers these files without a spec change.closes: #2509
Limitations and follow-up