[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/command-reference/roxctl-version.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

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.

[ocpdocs-previewbot]

🤖 Mon May 18 18:15:23 - Prow CI generated the docs preview:
https://111795--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

[agantony]

PR Review Guide: roxctl-version DITA Refactoring

Summary

This PR refactors roxctl-version.adoc to follow Red Hat modular documentation standards and resolve DITA conversion errors. This is the simplest roxctl refactoring with minimal inline content and a straightforward command structure.

Files Changed: 5 (+40, -12)
Pattern: Minimal CLI Reference (Pattern 9)
Netlify Preview: https://111795--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-version.html

---

What Changed

Assembly refactored:

• cli/command-reference/roxctl-version.adoc - Inline content extracted to modules

New modules created (2):

1. modules/roxctl-version-overview.adoc - Command overview (CONCEPT)
2. modules/roxctl-version-usage.adoc - Usage syntax (REFERENCE)

Existing modules updated (2):

• modules/roxctl-version-command-options.adoc - Title changed, abstract added
• modules/options-inherited-from-the-parent-command.adoc - Abstract role added

Module Hierarchy:

roxctl-version.adoc (assembly)
├── roxctl-version-overview.adoc (+1)
├── roxctl-version-usage.adoc (+2)
├── roxctl-version-command-options.adoc (+2)
└── options-inherited-from-the-parent-command.adoc (+1)

---

Step-by-Step Review

1. Main Page

Preview: https://111795--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-version.html

Check:

• ✅ Assembly abstract appears at top
• ✅ Table of contents renders correctly
• ✅ Command overview section displays
• ✅ Usage syntax visible
• ✅ Options section (roxctl version command options)
• ✅ Inherited options section

2. Section: roxctl version (Overview)

Location: First content section after TOC

Check:

• ✅ Heading: "roxctl version"
• ✅ Abstract: "Display the current roxctl version."
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

3. Section: roxctl version usage

Location: Scroll to "roxctl version usage" heading

Check:

• ✅ Heading: "roxctl version usage"
• ✅ Abstract: "Usage syntax for the `roxctl version` command."
• ✅ Usage syntax: `$ roxctl version [flags]`
• ✅ Heading level is H3 (from H1 with leveloffset=+2)

4. Section: Options

Location: Scroll to "Options" heading

Check:

• ✅ Heading changed from "roxctl version command options" to "Options"
• ✅ Abstract: "Options for the `roxctl version` command."
• ✅ Options table with 1 row (`--json` flag)
• ✅ Heading level is H3 (from H1 with leveloffset=+2)

Key changes to this module:

• Title simplified: "roxctl version command options" → "Options"
• Added [role="_abstract"] attribute
• Updated abstract text
• Fixed file path in comment
• Removed trailing whitespace

5. Section: Options inherited from the parent command

Location: Scroll to "roxctl version command options inherited from the parent command" heading

Check:

• ✅ Full heading title appears
• ✅ Abstract describes inherited options
• ✅ Options table with 11 rows (all roxctl global options)
• ✅ Heading level is H2 (from H1 with leveloffset=+1)

---

Verification Checklist

Structural:

• All headings at correct hierarchy (H1 → H2 → H3)
• TOC includes all sections
• No broken includes
• Proper 2-level hierarchy

Content:

• Command description present
• Usage syntax displays correctly
• Options table renders (1 row)
• Inherited options table renders (11 rows)
• No content lost
• Abstracts appear under each section

DITA Compliance:

• Assembly has [role="_abstract"]
• Each module has [role="_abstract"]
• Content types correct (CONCEPT/REFERENCE)
• Overview module is CONCEPT
• Usage/options modules are REFERENCE

---

Unique Characteristics

This PR is unique in the roxctl refactoring series:

Feature	Other PRs	This PR
Files changed	15-100	5 (smallest)
New modules	8-70	2 (minimal)
Command structure	Multiple commands/subcommands	Single simple command
Assembly-level options	Yes (some)	No
Available commands table	Yes	No
Subcommands	Yes (most)	No
Hierarchy depth	2-4 levels	2 levels (simplest)

Pattern 9: Minimal CLI reference assembly for simple commands with no subcommands.

---

Related PRs

• #111737 - roxctl-declarative-config (3-level)
• #111782 - roxctl-netpol (3-level)
• #111785 - roxctl-image (assembly-level options)
• #111791 - roxctl-sensor (3-level)
• #111792 - roxctl-central (4-level, 100 files)

---

📝 Review guide saved: /tmp/pr-111795-review-guide.md

[maxwelldb]

@agantony This tool is mistaking PR numbers. #111738 is not a roxctl PR.

[agantony]

@agantony This tool is mistaking PR numbers. #111738 is not a roxctl PR.

Thanks for bringing this to my attention. I removed all the incorrect references.

[openshift-ci]

@agantony: all tests passed!

Full PR test history. Your PR dashboard.

Details

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 kubernetes-sigs/prow repository. I understand the commands that are listed here.

[jlprevatt]

LGTM

[agantony]

/cherrypick rhacs-docs-4.11

[agantony]

/cherrypick rhacs-docs-4.10

[agantony]

/cherrypick rhacs-docs-4.9

[openshift-cherrypick-robot]

@agantony: new pull request created: #113800

Details

In response to this:

/cherrypick rhacs-docs-4.11

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 kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@agantony: new pull request created: #113801

Details

In response to this:

/cherrypick rhacs-docs-4.10

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 kubernetes-sigs/prow repository.

[openshift-cherrypick-robot]

@agantony: new pull request created: #113802

Details

In response to this:

/cherrypick rhacs-docs-4.9

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 kubernetes-sigs/prow repository.