chore: Align docs to templates, style and wording before release#787
Conversation
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
…eps to all docs. On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
✅ Deploy Preview for open-component-model ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
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:
📝 WalkthroughWalkthroughDocumentation-only edits across many pages: terminology changed from “FluxCD” to “Flux,” relref/link syntax and section headings standardized, tutorials updated with “What You’ll Learn,” working-directory create/cd and rm -rf cleanup steps, and Next Steps / Related Documentation lists reorganized. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/docs/getting-started/setup-controller-environment.md`:
- Around line 295-296: Rewrite the two sentences "To remove the local kind
cluster after testing you can execute the following command." and "You can just
keep it when you want to use the same cluster for the next steps in the
tutorial." to a single clearer pair of lines that read smoothly and match the
guide's tone — e.g. first tell the reader how to delete the local kind cluster
after testing, then state that keeping the cluster is fine if they plan to reuse
it for subsequent tutorial steps; ensure concise phrasing and consistent voice
with surrounding instructions.
In `@content/docs/tutorials/advanced-component-constructor.md`:
- Line 627: Replace the non-idempotent cleanup command "rm -r
/tmp/ocm-multi-component" with the force-and-recursive variant "rm -rf
/tmp/ocm-multi-component" so the tutorial step no longer errors when the
directory is already absent.
In `@content/docs/tutorials/configure-resolvers.md`:
- Line 332: Replace the non-idempotent cleanup command "rm -r
/tmp/ocm-resolver-tutorial" with a recursive + force removal to make re-runs
safe; locate the occurrence of that exact command in the configure-resolvers
tutorial content and change it to "rm -rf /tmp/ocm-resolver-tutorial" so
repeated cleanup won't fail when the directory is already gone.
In `@content/docs/tutorials/deploy-helm-chart-bootstrap.md`:
- Line 101: The Mermaid diagram's class assignment references the old subgraph
identifier fluxCD but the subgraph was renamed to flux, so update the class
definition/reference to use the new identifier "flux" (e.g., change any
occurrence of classDef/class or class assignments targeting fluxCD to target
flux) ensuring the class styling lines that reference fluxCD now match the
subgraph name flux so the styles apply correctly to subgraph flux.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 81a12a6b-d05c-4db7-ab16-c30190f8f704
📒 Files selected for processing (11)
content/docs/concepts/ocm-controllers.mdcontent/docs/concepts/transfer-concept.mdcontent/docs/getting-started/deploy-helm-chart.mdcontent/docs/getting-started/setup-controller-environment.mdcontent/docs/how-to/air-gap-transfer.mdcontent/docs/how-to/transfer-helm-charts.mdcontent/docs/overview/how-ocm-works.mdcontent/docs/tutorials/advanced-component-constructor.mdcontent/docs/tutorials/configure-resolvers.mdcontent/docs/tutorials/deploy-helm-chart-bootstrap.mdcontent/docs/tutorials/signing-and-verification.md
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
frewilhelm
left a comment
There was a problem hiding this comment.
Please make sure that it renders correctly :D
Co-authored-by: Frederic Wilhelm <fre.wilhelm@gmail.com> Signed-off-by: Gerald Morrison <67469729+morri-son@users.noreply.github.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
…ates-and-wording On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
|
@coderabbitai review |
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content/docs/how-to/container-image-usage.md`:
- Line 34: The step heading "Create a simple component constructor" inside the
{{< step >}} block is using an H2 (##) but must be an H3 (###); update this and
the other occurrences mentioned (lines with the same pattern at the other step
blocks) so all step titles within {{< step >}} use level-3 headings (e.g.,
change "## Create a simple component constructor" to "### Create a simple
component constructor") to match the template's visual hierarchy.
- Around line 84-85: Replace the blockquote-style notes that start with the
emoji heading "📣📣 **Note**" (the instances containing the sentence about
updating the `identity` fields if you don't use `ghcr.io`) with the project’s
standard Hugo callout shortcode; locate the two occurrences (the one beginning
with "📣📣 **Note**" and the later repeated note) and swap each blockquote
wrapper for the callout shortcode wrapper while keeping the inner text identical
and preserving code formatting/inline backticks.
In `@content/docs/how-to/migrate-from-deprecated-resolvers.md`:
- Line 262: The document contains a second top-level heading "Related
Documentation" using a single "#" which triggers MD025; change that heading to
an H2 by replacing "# Related Documentation" with "## Related Documentation" so
the file keeps a single H1 title and satisfies markdownlint.
In `@content/docs/how-to/resolve-components-from-multiple-repositories.md`:
- Line 139: Change the markdown header string "## Related documentation" to
title case "## Related Documentation" to match the repository's standardized
section naming; locate the header exactly as "## Related documentation" in the
document and update it to "## Related Documentation".
- Around line 136-137: Update the duplicated link label "Tutorial: Working with
Resolvers Tutorial" so it uses a single, consistent form (e.g., "Tutorial:
Working with Resolvers" or "Working with Resolvers") while keeping the same
relref target ({{< relref "docs/tutorials/configure-resolvers.md" >}}); replace
the existing label text to remove the extra "Tutorial".
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 617aa74d-c78e-414b-9554-c7d556ddccae
📒 Files selected for processing (15)
content/docs/concepts/component-identity.mdcontent/docs/concepts/resolvers.mdcontent/docs/concepts/transfer-concept.mdcontent/docs/how-to/air-gap-transfer.mdcontent/docs/how-to/container-image-usage.mdcontent/docs/how-to/custom-rbac.mdcontent/docs/how-to/generate-signing-keys.mdcontent/docs/how-to/legacy-credential-compatibility.mdcontent/docs/how-to/migrate-from-deprecated-resolvers.mdcontent/docs/how-to/model-products.mdcontent/docs/how-to/resolve-components-from-multiple-repositories.mdcontent/docs/how-to/transfer-helm-charts.mdcontent/docs/overview/core-model.mdcontent/docs/tutorials/advanced-component-constructor.mdcontent/docs/tutorials/configure-credentials-for-controllers.md
✅ Files skipped from review due to trivial changes (9)
- content/docs/how-to/generate-signing-keys.md
- content/docs/how-to/custom-rbac.md
- content/docs/overview/core-model.md
- content/docs/how-to/legacy-credential-compatibility.md
- content/docs/tutorials/configure-credentials-for-controllers.md
- content/docs/how-to/transfer-helm-charts.md
- content/docs/how-to/model-products.md
- content/docs/concepts/component-identity.md
- content/docs/concepts/transfer-concept.md
🚧 Files skipped from review as they are similar to previous changes (1)
- content/docs/tutorials/advanced-component-constructor.md
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
<!-- markdownlint-disable MD041 --> #### What this PR does / why we need it Align all docs to same look-and-feel and templates - Use steps callouts in how-tos, gettings started and tutorials - Name Flux consistently - Use "What you'll learn" as "## Header" in all docs - Add Next Steps to all docs and sort items to "next steps" and "related documentation" --------- Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> Co-authored-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> be71642
What this PR does / why we need it
Align all docs to same look-and-feel and templates