CNTRLPLANE-3945: Migrate documentation tooling from mkdocs-material to zensical - #9139
Merged
Conversation
Contributor
|
Pipeline controller notification For optional jobs, comment This repository is configured in: LGTM mode |
openshift-ci-robot
added
the
jira/valid-reference
|
@celebdor: This pull request references CNTRLPLANE-3945 which is a valid jira issue. Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set. DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository. |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe documentation toolchain migrates from MkDocs to Zensical 0.0.51. The project uses Sequence Diagram(s)sequenceDiagram
participant Makefile
participant Zensical
participant SiteServer
participant Playwright
participant ComparisonReport
Makefile->>Zensical: build base and head sites
Makefile->>SiteServer: serve generated sites
SiteServer->>Playwright: provide documentation routes
Playwright->>ComparisonReport: write screenshots and pixel differences
ComparisonReport->>Makefile: provide JSON and HTML reports
Suggested reviewers: 🚥 Pre-merge checks | ✅ 11✅ Passed checks (11 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Comment |
openshift-ci
Bot
added
area/documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
docs/Makefile (1)
2-2: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winPin the container image instead of using
latest.Both containerized targets consume
IMG, so:latestcan silently change the documentation toolchain between runs. Pin an approved release digest and update it intentionally. (hub.docker.com)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/Makefile` at line 2, Update the IMG variable in the Makefile to use the approved Zensical container release pinned by an immutable digest instead of the latest tag, preserving its use by both containerized targets..github/workflows/docs-build-reusable.yaml (1)
18-18: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winPin the uv version used by CI.
This action has no
versioninput. Unless another repository-level configuration constrains it,setup-uvinstalls the latest uv release, allowing the CI toolchain to change independently ofuv.lock. (github.com)As per path instructions, CI/CD dependencies should remain reproducible and supply-chain controlled.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs-build-reusable.yaml at line 18, Update the setup-uv action invocation in the workflow to specify an explicit uv version compatible with the repository’s lockfile, while preserving the existing action commit pin. Use the action’s supported version input so CI does not install the moving latest release.Source: Path instructions
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/content/contribute/contribute-docs.md`:
- Around line 51-63: Update the preview URL in
docs/content/contribute/contribute-docs.md (lines 51-63) and
docs/content/how-to/ci/docs-preview.md (lines 29-36) from 0.0.0.0:8000 to
127.0.0.1:8000, leaving the serving commands unchanged.
In `@docs/Makefile`:
- Around line 4-6: Update the docs Makefile build target to invoke zensical
through uv with the frozen dependency environment, matching the docs workflow’s
`uv run --frozen` behavior while preserving the existing strict build arguments.
In `@docs/pyproject.toml`:
- Line 7: Change the Zensical dependency in the docs manifest to the exact
version 0.0.51 instead of a minimum-version constraint, then regenerate
docs/uv.lock so it remains consistent with the pinned dependency.
---
Nitpick comments:
In @.github/workflows/docs-build-reusable.yaml:
- Line 18: Update the setup-uv action invocation in the workflow to specify an
explicit uv version compatible with the repository’s lockfile, while preserving
the existing action commit pin. Use the action’s supported version input so CI
does not install the moving latest release.
In `@docs/Makefile`:
- Line 2: Update the IMG variable in the Makefile to use the approved Zensical
container release pinned by an immutable digest instead of the latest tag,
preserving its use by both containerized targets.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: d46b5a66-6b9a-4c88-a445-10931787447c
⛔ Files ignored due to path filters (1)
docs/uv.lockis excluded by!**/*.lock
📒 Files selected for processing (8)
.github/workflows/docs-build-reusable.yamldocs/Dockerfiledocs/Makefiledocs/content/contribute/contribute-docs.mddocs/content/how-to/ci/docs-preview.mddocs/mkdocs.ymldocs/pyproject.tomldocs/requirements.txt
💤 Files with no reviewable changes (2)
- docs/Dockerfile
- docs/requirements.txt
Collaborator
Author
|
/jira refresh |
|
@celebdor: This pull request references CNTRLPLANE-3945 which is a valid jira issue. DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/Makefile`:
- Around line 16-21: Update the contributor instructions in docs/README.md to
remove the stale make image command and start the containerized build workflow
with make build-containerized, matching the available Makefile targets.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: d45305f3-0d30-4f67-99f5-d56baf8c2a2a
⛔ Files ignored due to path filters (2)
docs/content/reference/aggregated-docs.mdis excluded by!docs/content/reference/aggregated-docs.mddocs/uv.lockis excluded by!**/*.lock
📒 Files selected for processing (8)
.github/workflows/docs-build-reusable.yamldocs/Dockerfiledocs/Makefiledocs/content/contribute/contribute-docs.mddocs/content/how-to/ci/docs-preview.mddocs/mkdocs.ymldocs/pyproject.tomldocs/requirements.txt
💤 Files with no reviewable changes (2)
- docs/requirements.txt
- docs/Dockerfile
Collaborator
Author
|
docs-build is expected to fail until this PR merges due to the changes in requirements. |
openshift-ci
Bot
added
the
needs-rebase
openshift-ci
Bot
removed
the
needs-rebase
mkdocs-material is approaching end of life. Switch to zensical, which provides built-in mermaid support (removing the mermaid2 plugin), and replace pip with uv for dependency management with hash-verified lockfile for supply chain security. - Remove mermaid2 plugin and use zensical's native mermaid rendering - Replace pip/requirements.txt with uv/pyproject.toml and uv.lock - Delete custom Dockerfile in favor of official zensical/zensical image - Update CI workflow to use setup-uv with --frozen for hash verification - Update contributor and preview docs to reflect new tooling Signed-off-by: Antoni Segura Puimedon <antoni@redhat.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/README.md`:
- Around line 5-6: Renumber the setup commands in the documentation list from 2.
and 3. to 1. and 2., respectively, after the removed make image step.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 1ebb98af-65cd-47d4-bddb-de53c0ecd051
⛔ Files ignored due to path filters (2)
docs/content/reference/aggregated-docs.mdis excluded by!docs/content/reference/aggregated-docs.mddocs/uv.lockis excluded by!**/*.lock
📒 Files selected for processing (11)
.github/workflows/docs-build-reusable.yamldocs/Dockerfiledocs/Makefiledocs/README.mddocs/content/contribute/contribute-docs.mddocs/content/how-to/ci/docs-preview.mddocs/content/how-to/ci/github-actions.mddocs/content/how-to/ci/triage/presubmit-failures.mddocs/mkdocs.ymldocs/pyproject.tomldocs/requirements.txt
💤 Files with no reviewable changes (2)
- docs/Dockerfile
- docs/requirements.txt
🚧 Files skipped from review as they are similar to previous changes (7)
- docs/content/how-to/ci/github-actions.md
- docs/content/how-to/ci/triage/presubmit-failures.md
- docs/pyproject.toml
- .github/workflows/docs-build-reusable.yaml
- docs/mkdocs.yml
- docs/content/how-to/ci/docs-preview.md
- docs/content/contribute/contribute-docs.md
Comment on lines
+5
to
+6
| 2. Run `make build-containerized` to build the containerized version of the image | ||
| 3. Run `make serve-containerized` to serve up the docs website locally |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Renumber the setup commands.
After removing the make image step, the first remaining command is numbered 2. and the second is 3.. Change them to 1. and 2..
Proposed fix
-2. Run `make build-containerized` to build the containerized version of the image
-3. Run `make serve-containerized` to serve up the docs website locally
+1. Run `make build-containerized` to build the containerized version of the image
+2. Run `make serve-containerized` to serve up the docs website locally📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 2. Run `make build-containerized` to build the containerized version of the image | |
| 3. Run `make serve-containerized` to serve up the docs website locally | |
| 1. Run `make build-containerized` to build the containerized version of the image | |
| 2. Run `make serve-containerized` to serve up the docs website locally |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/README.md` around lines 5 - 6, Renumber the setup commands in the
documentation list from 2. and 3. to 1. and 2., respectively, after the removed
make image step.
Zensical derives page titles from the file itself (frontmatter or first heading), falling back to the filename. Pages that had no intrinsic title previously got their displayed title from the mkdocs.yml nav label, but now render as the raw filename (e.g. "Watching dp" instead of "Watching the Data Plane"). Add explicit frontmatter title: fields to restore the original titles. Signed-off-by: Antoni Segura Puimedon <antoni@redhat.com> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
openshift-ci
Bot
added
area/platform/aws
Contributor
There was a problem hiding this comment.
Actionable comments posted: 12
🧹 Nitpick comments (1)
docs/Makefile (1)
45-45: 🔒 Security & Privacy | 🔵 Trivial | 🏗️ Heavy liftSecurity Misconfiguration (CWE-829): Inclusion of Functionality from Untrusted Control Sphere
Reachability: Internal · Exploitability: Difficult
Use the hash-pinned base-site dependencies.
uv run --withresolves unversioned MkDocs packages and does not consume the hash-pinned dependency contract. Use the pinned contract or a dedicated frozen lock so the build uses controlled versions and hashes.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/Makefile` at line 45, Update the docs build command in the Makefile target around mkdocs build to stop resolving unversioned packages via uv run --with. Reuse the repository’s hash-pinned dependency contract or dedicated frozen lock, ensuring the MkDocs build installs only controlled versions with verified hashes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/compare/compare.mjs`:
- Around line 121-123: Update screenshotPages to collect and return routes where
page.goto or page.screenshot throws instead of only logging them; represent each
failed route with an explicit error status in results.json and propagate that
status into the HTML report so failures are not classified as new-only/old-only
or omitted.
- Around line 291-303: Replace the clickable `.page-header` div disclosure in
the comparison markup with a keyboard-operable native `details`/`summary` pair
or an equivalent button using `aria-expanded`. Preserve the existing page header
content and comparison body, ensuring the control exposes and toggles the open
state accessibly.
- Around line 326-329: In the comparison setup around screenshotsOld,
screenshotsNew, and screenshotsDiff, remove each existing screenshot directory
before recreating outputDir or capturing pages. Use recursive cleanup that
safely handles missing directories, then preserve the current directory creation
and capture flow.
- Around line 84-91: Validate the resolved filePath in the createServer request
handler before the existsSync and readFile operations, rejecting requests whose
normalized path falls outside siteDir, including traversal segments in req.url.
Preserve normal index.html and directory-index resolution for paths contained
within siteDir.
In `@docs/content/contribute/contribute-docs.md`:
- Line 71: Update the five new root-level fenced code blocks in the Markdown
document to comply with the repository’s MD046 indentation style, preserving
their shell-language annotations and content; alternatively, change the
repository markdownlint rule only if fenced blocks are intentionally required.
Run make verify-codespell for the Markdown changes.
In `@docs/content/labs/Dual/mgmt-cluster/compact-dual.md`:
- Line 2: Update the document title from “Openshift Compact Dual” to “OpenShift
Compact Dual,” preserving the existing title wording and capitalization of the
product name.
In `@docs/content/labs/IPv4/mgmt-cluster/compact-ipv4.md`:
- Around line 1-4: Update the frontmatter title to use the correct product
capitalization: change “Openshift” to “OpenShift” while preserving the rest of
the title.
In `@docs/content/labs/IPv6/mgmt-cluster/compact-ipv6.md`:
- Line 2: Update the document frontmatter title from “Openshift Compact IPv6” to
use the official “OpenShift” capitalization, preserving the rest of the title
unchanged.
In `@docs/content/reference/manifests/ibmcloud/4.10.md`:
- Line 2: Quote the numeric title values in
docs/content/reference/manifests/ibmcloud/4.9.md:2-2,
docs/content/reference/manifests/ibmcloud/4.10.md:2-2,
docs/content/reference/manifests/ibmcloud/4.11.md:2-2,
docs/content/reference/manifests/ibmcloud/4.12.md:2-2, and
docs/content/reference/manifests/ibmcloud/4.13.md:2-2 so YAML preserves each
version exactly, including trailing zeros.
In `@docs/Makefile`:
- Around line 54-55: Update the documentation build recipe around the zensical
build command to remove any existing site output before building, preserve and
check the build exit status instead of masking it with || true, and execute mv
site site-head only after a successful build. Ensure failed builds stop the
recipe without moving stale or partial output.
- Around line 37-46: Update the compare-build-base target to validate the
site-base cache against the resolved BASE commit and a successful-build marker,
rather than only checking directory existence. Rebuild when the cached commit
differs, metadata is missing, or the previous build did not complete
successfully; write the marker and resolved commit only after mkdocs build
succeeds, while preserving reuse for the same BASE.
- Around line 49-55: Update the compare-build-head target to rebuild site-head
on every comparison instead of skipping when the directory exists. Remove the
site-head existence guard, clear or replace the prior output before running the
zensical build, and preserve the resulting build under site-head so current
committed and uncommitted working-tree changes are included.
---
Nitpick comments:
In `@docs/Makefile`:
- Line 45: Update the docs build command in the Makefile target around mkdocs
build to stop resolving unversioned packages via uv run --with. Reuse the
repository’s hash-pinned dependency contract or dedicated frozen lock, ensuring
the MkDocs build installs only controlled versions with verified hashes.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 1ca7696e-f2a8-4d27-8100-c4fc28b45d71
⛔ Files ignored due to path filters (1)
docs/compare/pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (57)
docs/.gitignoredocs/Makefiledocs/compare/compare.mjsdocs/compare/package.jsondocs/content/contribute/branch-process.mddocs/content/contribute/contribute-docs.mddocs/content/how-to/disconnected/idms-icsp-for-management-clusters.mddocs/content/how-to/sdn/other-sdn-providers.mddocs/content/labs/Dual/hostedcluster/baremetalhost.mddocs/content/labs/Dual/hostedcluster/hostedcluster.mddocs/content/labs/Dual/hostedcluster/index.mddocs/content/labs/Dual/hostedcluster/infraenv.mddocs/content/labs/Dual/hostedcluster/nodepool.mddocs/content/labs/Dual/hostedcluster/worker-nodes.mddocs/content/labs/Dual/hypervisor/redfish-for-vms.mddocs/content/labs/Dual/mgmt-cluster/compact-dual.mddocs/content/labs/Dual/mgmt-cluster/index.mddocs/content/labs/Dual/mgmt-cluster/network.mddocs/content/labs/IPv4/hostedcluster/baremetalhost.mddocs/content/labs/IPv4/hostedcluster/hostedcluster.mddocs/content/labs/IPv4/hostedcluster/index.mddocs/content/labs/IPv4/hostedcluster/infraenv.mddocs/content/labs/IPv4/hostedcluster/nodepool.mddocs/content/labs/IPv4/hostedcluster/worker-nodes.mddocs/content/labs/IPv4/hypervisor/redfish-for-vms.mddocs/content/labs/IPv4/mgmt-cluster/compact-ipv4.mddocs/content/labs/IPv4/mgmt-cluster/index.mddocs/content/labs/IPv4/mgmt-cluster/network.mddocs/content/labs/IPv6/hostedcluster/baremetalhost.mddocs/content/labs/IPv6/hostedcluster/hostedcluster.mddocs/content/labs/IPv6/hostedcluster/index.mddocs/content/labs/IPv6/hostedcluster/infraenv.mddocs/content/labs/IPv6/hostedcluster/nodepool.mddocs/content/labs/IPv6/hostedcluster/worker-nodes.mddocs/content/labs/IPv6/hypervisor/redfish-for-vms.mddocs/content/labs/IPv6/mgmt-cluster/compact-ipv6.mddocs/content/labs/IPv6/mgmt-cluster/index.mddocs/content/labs/IPv6/mgmt-cluster/network.mddocs/content/labs/common/hypervisor/network-manager-dispatcher.mddocs/content/labs/common/mce/agentserviceconfig.mddocs/content/labs/common/mce/index.mddocs/content/labs/common/mce/multicluster-engine.mddocs/content/labs/common/mirror/ICSP-IDMS.mddocs/content/labs/common/mirror/mirroring.mddocs/content/labs/common/tls-certificates.mddocs/content/labs/common/watching/watching-cp.mddocs/content/labs/common/watching/watching-dp.mddocs/content/recipes/common/control-plane-metrics-forwarding.mddocs/content/recipes/common/exposing-dataplane-with-metallb.mddocs/content/reference/architecture/mce-and-agent.mddocs/content/reference/infrastructure/agent.mddocs/content/reference/infrastructure/aws.mddocs/content/reference/manifests/ibmcloud/4.10.mddocs/content/reference/manifests/ibmcloud/4.11.mddocs/content/reference/manifests/ibmcloud/4.12.mddocs/content/reference/manifests/ibmcloud/4.13.mddocs/content/reference/manifests/ibmcloud/4.9.md
Comment on lines
+291
to
+303
| <div class="page-header" onclick="this.nextElementSibling.classList.toggle('open')"> | ||
| <span>${r.page}</span> | ||
| <span class="badge ${badge}">${r.diffPercent}% diff</span> | ||
| </div> | ||
| <div class="page-body"> | ||
| <h3>Side by side</h3> | ||
| <div class="compare"> | ||
| <div><h4>Old</h4><img src="screenshots-old/${file}" loading="lazy"></div> | ||
| <div><h4>New</h4><img src="screenshots-new/${file}" loading="lazy"></div> | ||
| </div> | ||
| <h3>Diff overlay</h3> | ||
| <div class="diff-img"><img src="screenshots-diff/${file}" loading="lazy"></div> | ||
| </div> |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use a keyboard-operable disclosure control.
The clickable .page-header is a div with no keyboard interaction or state semantics. Keyboard users cannot open the changed-page comparison.
Use a native details and summary pair, or use a button with aria-expanded.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/compare/compare.mjs` around lines 291 - 303, Replace the clickable
`.page-header` div disclosure in the comparison markup with a keyboard-operable
native `details`/`summary` pair or an equivalent button using `aria-expanded`.
Preserve the existing page header content and comparison body, ensuring the
control exposes and toggles the open state accessibly.
| changes, navigation restructuring), you can generate a visual diff against the | ||
| current `main` branch: | ||
|
|
||
| ```shell |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the new MD046 violations.
The supplied markdownlint output reports MD046 for the five new root-level fenced code blocks. Convert them to the repository's expected indented style, or update the repository rule if fenced blocks are intentional.
As per coding guidelines, run make verify-codespell for Markdown files.
Example
-```shell
+ ```shell
...
-```
+ ```Also applies to: 82-82, 88-88, 95-95, 113-113
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 71-71: Code block style
Expected: indented; Actual: fenced
(MD046, code-block-style)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/content/contribute/contribute-docs.md` at line 71, Update the five new
root-level fenced code blocks in the Markdown document to comply with the
repository’s MD046 indentation style, preserving their shell-language
annotations and content; alternatively, change the repository markdownlint rule
only if fenced blocks are intentionally required. Run make verify-codespell for
the Markdown changes.
Sources: Coding guidelines, Linters/SAST tools
Adds a Playwright-based screenshot comparison tool that diffs every page
between two built doc sites and generates an HTML report with side-by-side
views and pixel-level diff overlays.
Usage:
make compare # compare working tree against main
make compare BASE=v4.18 # compare against a specific ref
make compare-serve # serve the report locally
make compare-clean # remove generated artifacts
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
Note GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer. |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
docs/content/contribute/contribute-docs.md (1)
71-74:⚠️ Potential issue | 🟡 MinorUse the repository's Markdown code-block style.
The five new root-level fenced blocks trigger MD046. Convert them to the repository's expected indented style, or update the Markdown rule if fenced blocks are intentional.
As per coding guidelines, run
make verify-codespellfor this Markdown file.Also applies to: 82-84, 88-90, 95-107, 113-115
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/content/contribute/contribute-docs.md` around lines 71 - 74, Convert the referenced root-level fenced code blocks in the contribution documentation to the repository’s expected indented Markdown code-block style, unless the project’s Markdown configuration explicitly permits fenced blocks; update the rule only if that style is intentional. Run make verify-codespell for the modified Markdown file and resolve any reported issues.Sources: Coding guidelines, Linters/SAST tools
docs/Makefile (1)
47-48:⚠️ Potential issue | 🟠 MajorGate cached and promoted sites on successful builds.
Both recipes continue after the Zensical command. A failed build can leave missing cache metadata, cache metadata in the detached worktree, or partial output promoted as a valid site.
docs/Makefile#L47-L48: run the BASE build in a subshell and write$(CURDIR)/site-base/.commitonly inside a successful-build branch.docs/Makefile#L53-L56: movesitetosite-headonly after a successful build, or build into a temporary directory and rename it after success.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/Makefile` around lines 47 - 48, Gate both documentation build recipes on successful Zensical completion: in docs/Makefile lines 47-48, run the BASE build in a subshell and write site-base/.commit only from its success branch; in lines 53-56, promote site to site-head only after the build succeeds, preferably by building to a temporary directory and renaming it after success.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/Makefile`:
- Line 47: The base-site build command in the Makefile target must use the
toolchain and dependency files from BASE rather than assuming the worktree
contains Zensical configuration. Update the command around the BASE/worktree
build flow to invoke BASE’s established build command with its pyproject.toml
and uv.lock, while preserving the existing output directory.
---
Duplicate comments:
In `@docs/content/contribute/contribute-docs.md`:
- Around line 71-74: Convert the referenced root-level fenced code blocks in the
contribution documentation to the repository’s expected indented Markdown
code-block style, unless the project’s Markdown configuration explicitly permits
fenced blocks; update the rule only if that style is intentional. Run make
verify-codespell for the modified Markdown file and resolve any reported issues.
In `@docs/Makefile`:
- Around line 47-48: Gate both documentation build recipes on successful
Zensical completion: in docs/Makefile lines 47-48, run the BASE build in a
subshell and write site-base/.commit only from its success branch; in lines
53-56, promote site to site-head only after the build succeeds, preferably by
building to a temporary directory and renaming it after success.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited)
Review profile: CHILL
Plan: Enterprise
Run ID: 4b09f64b-ccfe-4d40-8f8c-5cc9658502a2
⛔ Files ignored due to path filters (3)
docs/compare/pnpm-lock.yamlis excluded by!**/pnpm-lock.yamldocs/content/reference/aggregated-docs.mdis excluded by!docs/content/reference/aggregated-docs.mddocs/uv.lockis excluded by!**/*.lock
📒 Files selected for processing (66)
.github/workflows/docs-build-reusable.yamldocs/.gitignoredocs/Dockerfiledocs/Makefiledocs/README.mddocs/compare/compare.mjsdocs/compare/package.jsondocs/content/contribute/branch-process.mddocs/content/contribute/contribute-docs.mddocs/content/how-to/ci/docs-preview.mddocs/content/how-to/ci/github-actions.mddocs/content/how-to/ci/triage/presubmit-failures.mddocs/content/how-to/disconnected/idms-icsp-for-management-clusters.mddocs/content/how-to/sdn/other-sdn-providers.mddocs/content/labs/Dual/hostedcluster/baremetalhost.mddocs/content/labs/Dual/hostedcluster/hostedcluster.mddocs/content/labs/Dual/hostedcluster/index.mddocs/content/labs/Dual/hostedcluster/infraenv.mddocs/content/labs/Dual/hostedcluster/nodepool.mddocs/content/labs/Dual/hostedcluster/worker-nodes.mddocs/content/labs/Dual/hypervisor/redfish-for-vms.mddocs/content/labs/Dual/mgmt-cluster/compact-dual.mddocs/content/labs/Dual/mgmt-cluster/index.mddocs/content/labs/Dual/mgmt-cluster/network.mddocs/content/labs/IPv4/hostedcluster/baremetalhost.mddocs/content/labs/IPv4/hostedcluster/hostedcluster.mddocs/content/labs/IPv4/hostedcluster/index.mddocs/content/labs/IPv4/hostedcluster/infraenv.mddocs/content/labs/IPv4/hostedcluster/nodepool.mddocs/content/labs/IPv4/hostedcluster/worker-nodes.mddocs/content/labs/IPv4/hypervisor/redfish-for-vms.mddocs/content/labs/IPv4/mgmt-cluster/compact-ipv4.mddocs/content/labs/IPv4/mgmt-cluster/index.mddocs/content/labs/IPv4/mgmt-cluster/network.mddocs/content/labs/IPv6/hostedcluster/baremetalhost.mddocs/content/labs/IPv6/hostedcluster/hostedcluster.mddocs/content/labs/IPv6/hostedcluster/index.mddocs/content/labs/IPv6/hostedcluster/infraenv.mddocs/content/labs/IPv6/hostedcluster/nodepool.mddocs/content/labs/IPv6/hostedcluster/worker-nodes.mddocs/content/labs/IPv6/hypervisor/redfish-for-vms.mddocs/content/labs/IPv6/mgmt-cluster/compact-ipv6.mddocs/content/labs/IPv6/mgmt-cluster/index.mddocs/content/labs/IPv6/mgmt-cluster/network.mddocs/content/labs/common/hypervisor/network-manager-dispatcher.mddocs/content/labs/common/mce/agentserviceconfig.mddocs/content/labs/common/mce/index.mddocs/content/labs/common/mce/multicluster-engine.mddocs/content/labs/common/mirror/ICSP-IDMS.mddocs/content/labs/common/mirror/mirroring.mddocs/content/labs/common/tls-certificates.mddocs/content/labs/common/watching/watching-cp.mddocs/content/labs/common/watching/watching-dp.mddocs/content/recipes/common/control-plane-metrics-forwarding.mddocs/content/recipes/common/exposing-dataplane-with-metallb.mddocs/content/reference/architecture/mce-and-agent.mddocs/content/reference/infrastructure/agent.mddocs/content/reference/infrastructure/aws.mddocs/content/reference/manifests/ibmcloud/4.10.mddocs/content/reference/manifests/ibmcloud/4.11.mddocs/content/reference/manifests/ibmcloud/4.12.mddocs/content/reference/manifests/ibmcloud/4.13.mddocs/content/reference/manifests/ibmcloud/4.9.mddocs/mkdocs.ymldocs/pyproject.tomldocs/requirements.txt
💤 Files with no reviewable changes (2)
- docs/requirements.txt
- docs/Dockerfile
🚧 Files skipped from review as they are similar to previous changes (61)
- docs/content/labs/Dual/hostedcluster/infraenv.md
- docs/content/how-to/sdn/other-sdn-providers.md
- docs/content/how-to/ci/github-actions.md
- docs/content/how-to/ci/triage/presubmit-failures.md
- docs/content/labs/IPv4/hostedcluster/hostedcluster.md
- docs/content/reference/manifests/ibmcloud/4.12.md
- docs/content/labs/Dual/hypervisor/redfish-for-vms.md
- docs/content/labs/common/mce/multicluster-engine.md
- docs/content/labs/Dual/mgmt-cluster/network.md
- .github/workflows/docs-build-reusable.yaml
- docs/content/labs/common/watching/watching-cp.md
- docs/content/labs/common/watching/watching-dp.md
- docs/content/labs/Dual/hostedcluster/index.md
- docs/content/contribute/branch-process.md
- docs/content/reference/manifests/ibmcloud/4.11.md
- docs/content/labs/IPv4/hypervisor/redfish-for-vms.md
- docs/content/labs/IPv6/mgmt-cluster/network.md
- docs/content/recipes/common/control-plane-metrics-forwarding.md
- docs/content/labs/common/hypervisor/network-manager-dispatcher.md
- docs/content/labs/IPv6/hostedcluster/nodepool.md
- docs/content/labs/IPv6/hostedcluster/infraenv.md
- docs/content/reference/manifests/ibmcloud/4.10.md
- docs/content/reference/infrastructure/agent.md
- docs/content/labs/Dual/hostedcluster/baremetalhost.md
- docs/content/labs/IPv6/hypervisor/redfish-for-vms.md
- docs/content/reference/architecture/mce-and-agent.md
- docs/content/labs/IPv6/hostedcluster/index.md
- docs/content/labs/IPv4/hostedcluster/nodepool.md
- docs/content/labs/IPv4/hostedcluster/infraenv.md
- docs/content/labs/IPv4/hostedcluster/index.md
- docs/content/labs/Dual/mgmt-cluster/index.md
- docs/.gitignore
- docs/content/labs/Dual/hostedcluster/nodepool.md
- docs/content/labs/IPv4/hostedcluster/baremetalhost.md
- docs/content/labs/Dual/hostedcluster/worker-nodes.md
- docs/content/labs/IPv6/hostedcluster/baremetalhost.md
- docs/content/reference/manifests/ibmcloud/4.13.md
- docs/content/labs/IPv6/mgmt-cluster/index.md
- docs/content/labs/Dual/mgmt-cluster/compact-dual.md
- docs/content/how-to/ci/docs-preview.md
- docs/content/labs/common/tls-certificates.md
- docs/compare/package.json
- docs/content/labs/common/mce/index.md
- docs/content/labs/IPv6/mgmt-cluster/compact-ipv6.md
- docs/content/reference/infrastructure/aws.md
- docs/content/labs/Dual/hostedcluster/hostedcluster.md
- docs/pyproject.toml
- docs/content/labs/common/mirror/mirroring.md
- docs/content/labs/common/mirror/ICSP-IDMS.md
- docs/content/labs/IPv4/hostedcluster/worker-nodes.md
- docs/compare/compare.mjs
- docs/content/how-to/disconnected/idms-icsp-for-management-clusters.md
- docs/content/labs/IPv6/hostedcluster/hostedcluster.md
- docs/content/labs/IPv4/mgmt-cluster/network.md
- docs/content/labs/IPv4/mgmt-cluster/compact-ipv4.md
- docs/mkdocs.yml
- docs/content/labs/IPv4/mgmt-cluster/index.md
- docs/content/labs/common/mce/agentserviceconfig.md
- docs/content/recipes/common/exposing-dataplane-with-metallb.md
- docs/content/reference/manifests/ibmcloud/4.9.md
- docs/content/labs/IPv6/hostedcluster/worker-nodes.md
| WORKTREE=$$(mktemp -d); \ | ||
| trap 'git -C .. worktree remove --force "$$WORKTREE" 2>/dev/null' EXIT; \ | ||
| git -C .. worktree add --detach "$$WORKTREE" "$(BASE)"; \ | ||
| cd "$$WORKTREE/docs" && uv run --frozen zensical build -d "$(CURDIR)/site-base"; \ |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
base_ref="${BASE:-main}"
for path in docs/pyproject.toml docs/uv.lock docs/requirements.txt docs/Makefile; do
if git cat-file -e "$base_ref:$path" 2>/dev/null; then
printf '== %s:%s ==\n' "$base_ref" "$path"
git show "$base_ref:$path" | sed -n '1,160p'
else
printf 'MISSING %s:%s\n' "$base_ref" "$path"
fi
done
printf '== build-tool references ==\n'
git show "$base_ref:docs/Makefile" 2>/dev/null |
rg -n 'mkdocs|zensical|uv run|pip' || trueRepository: openshift/hypershift
Length of output: 12762
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '== docs/Makefile =='
cat -n docs/Makefile | sed -n '1,110p'
printf '%s\n' '== relevant changes =='
git diff -- docs/Makefile | sed -n '1,220p'
printf '%s\n' '== related comparison/build references =='
rg -n -C 3 'WORKTREE|BASE|site-base|zensical|mkdocs|verify-parallel|comparison' . \
-g 'Makefile' -g '*.yml' -g '*.yaml' -g '*.md' -g '*.sh'Repository: openshift/hypershift
Length of output: 50377
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '== docs/Makefile =='
cat -n docs/Makefile | sed -n '1,100p'
printf '%s\n' '== docs/Makefile diff =='
git diff --unified=30 -- docs/Makefile | sed -n '1,240p'
printf '%s\n' '== narrow references =='
rg -n -C 5 'WORKTREE|site-base|BASE|zensical|mkdocs|verify-parallel' \
docs/Makefile Makefile .github docs \
-g 'Makefile' -g '*.yml' -g '*.yaml' -g '*.md' -g '*.sh' \
--glob '!docs/site/**' --glob '!docs/site-base/**' \
| sed -n '1,320p'Repository: openshift/hypershift
Length of output: 21023
Build the base site with the toolchain from BASE. For the default main ref, docs/pyproject.toml and docs/uv.lock are absent, while docs/Makefile uses mkdocs build. Line 47 therefore cannot reliably build the base site. Use the BASE build command and dependency files, or add a compatibility path for MkDocs Material.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/Makefile` at line 47, The base-site build command in the Makefile target
must use the toolchain and dependency files from BASE rather than assuming the
worktree contains Zensical configuration. Update the command around the
BASE/worktree build flow to invoke BASE’s established build command with its
pyproject.toml and uv.lock, while preserving the existing output directory.
Contributor
|
@celebdor: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
csrwng
added
the
approved
Contributor
|
[APPROVALNOTIFIER] This PR is APPROVED Approval requirements bypassed by manually added approval. This pull-request has been approved by: celebdor The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Contributor
|
/lgtm |
Contributor
|
Pipeline controller notification No second-stage tests were triggered for this PR. This can happen when:
Use |
1 task
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
4 participants
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.
Summary
uv.lockfor supply chain securitydocs/Dockerfilein favor of the officialzensical/zensicalcontainer imagesetup-uvwith--frozenfor hash verificationJira
https://redhat.atlassian.net/browse/CNTRLPLANE-3945
Test plan
cd docs && uv run zensical build --strictpassescd docs && make serve-containerizedserves the site🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores