[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/command-reference/roxctl-central.adoc by agantony · Pull Request #111792 · openshift/openshift-docs

agantony · 2026-05-18T11:49:46Z

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 · 2026-05-18T11:49:51Z

@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 · 2026-05-18T11:57:17Z

🤖 Tue May 19 12:32:41 - Prow CI generated the docs preview:
https://111792--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

openshift-ci · 2026-05-19T12:34:57Z

@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.

agantony · 2026-05-19T12:38:43Z

📚 Review Guide: roxctl central CLI Reference Modularization

Summary

This PR implements complete DITA-compliant modularization of the roxctl central CLI reference documentation, restructuring 126 files into a 3-level hierarchy pattern.

Jira: ROX-33164
Files Changed: 126 (1 assembly + 125 modules)
Line Changes: +1,983 / -972

📊 Module Structure

Hierarchy Overview

roxctl-central.adoc (Assembly)
├── Overview modules (3): overview, usage, available-commands
├── Parent commands (10): backup, cert, crs, login, whoami, db, debug, generate, init-bundles, userpki
│   ├── Each has: CONCEPT module (title + abstract only)
│   ├── Each has: Usage module (REFERENCE, syntax)
│   └── Some have: Options module (REFERENCE, options table)
└── Sub-commands (34): crs generate/list/revoke, db restore/generate, debug authz-trace/db/..., etc.
    ├── Each has: CONCEPT module (title + abstract only)
    ├── Each has: Usage module (REFERENCE, syntax)
    └── Some have: Options module (REFERENCE, options table)

Module Counts by Type

Type	Count	Leveloffset	Example
Assembly	1	N/A	`roxctl-central.adoc`
Assembly modules	3	+1, +2, +2	overview, usage, available-commands
Parent CONCEPT	10	+1	`roxctl-central-backup.adoc`
Parent usage	10	+2	`roxctl-central-backup-usage.adoc`
Parent options	7	+2	`roxctl-central-backup-options.adoc`
Sub CONCEPT	34	+2	`roxctl-central-crs-generate.adoc`
Sub usage	34	+3	`roxctl-central-crs-generate-usage.adoc`
Sub options	26	+3	`roxctl-central-crs-generate-flags.adoc`
Shared module	1	+1/+2	`options-inherited-from-parent-command.adoc`

Total: 126 files

🔍 Step-by-Step Review Instructions

Netlify Preview Base

Main page: https://111792--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-central.html

Review Sections

1️⃣ Assembly & Overview

Link: roxctl central main page

Check:

Assembly abstract present
Table of contents renders correctly
"roxctl central" overview (H2) → usage (H3) → available commands (H3)
Inherited options section (H2) with abstract

2️⃣ Simple Parent Commands

Links:

backup | cert | login | whoami

Check for each:

Command title (H2) with abstract paragraph only (no inline usage)
Usage subsection (H3) with syntax
Options subsection (H3) with table

3️⃣ Parent Commands with Sub-commands

crs (3 sub-commands) - Link

crs (H2) → usage (H3) → generate (H3) → usage (H4) → Options (H4)
Critical: Verify "Options" heading (not "Flags") in crs generate

db (multiple nested sub-commands) - Link

db (H2) → usage (H3) → options (H3)
Sub-commands: restore, generate, restore-cancel, restore-status
Nested commands: db-generate-k8s, db-generate-openshift (with hostpath/pvc variants)

debug (5 sub-commands) - Link

Sub-commands: authz-trace, db, download-diagnostics, dump, log
Each at H3 with usage at H4

generate (nested variants) - Link

Sub-commands: interactive, k8s, openshift
k8s/openshift variants: hostpath, pvc

init-bundles (4 sub-commands) - Link

Sub-commands: fetch-ca, generate, list, revoke

userpki (3 sub-commands) - Link

Sub-commands: create, delete, list

✅ Verification Checklist

Structural Compliance

No inline Usage in CONCEPT modules: All CONCEPT modules contain only title + abstract (no .Usage blocks)
Correct module types: CONCEPT for descriptions, REFERENCE for usage/options
Proper leveloffsets: +1 (parents), +2 (children), +3 (grandchildren)
Abstracts present: All modules have [role="_abstract"]
Terminology: "Options" used (not "Flags")

Content Integrity

No content loss: All usage syntax preserved
No content loss: All options tables preserved
No duplication: Usage appears only in usage modules, not in CONCEPT modules
Anchors preserved: Original [id="..."] maintained

Rendering Quality

Build success: ./scripts/prow-smoke-test.sh passes
Heading hierarchy: H1→H2→H3→H4 (no skips)
Table of contents: All sections linked correctly
Mobile responsive: Content readable on smaller screens

🎯 Key Quality Standards Met

DITA Compliance

✅ Topic-based authoring: CONCEPT (what) separated from REFERENCE (how)
✅ Single responsibility: Each module serves one clear purpose
✅ Reusability: Shared inherited options module used throughout
✅ Proper nesting: Correct heading level progression

Content Quality

✅ Complete: All 10 parent + 34 sub-commands documented
✅ Accurate: Usage syntax and options tables intact
✅ Consistent: Terminology standardized across all modules
✅ Accessible: Proper abstracts for all sections

Build Quality

✅ Clean build: No errors in smoke test
✅ Valid structure: All includes resolve correctly
✅ Backward compatible: Existing anchors preserved

📋 Quick Visual Check Guide

✅ Correct Structure

roxctl central backup              ← H2 (CONCEPT module)
  Brief description only           ← Abstract paragraph, NO usage here
  
  roxctl central backup usage      ← H3 (usage module)
    $ roxctl central backup [...]  ← Usage syntax
    
  Options                          ← H3 (options module)
    | Option | Description |       ← Options table

❌ What to Watch For

Duplicate usage (appearing in both CONCEPT and usage modules)
"Flags" terminology instead of "Options"
Missing abstracts
Inline usage in CONCEPT modules
Incorrect heading levels (H2→H4 skip)

🧪 Testing Commands

# Build test
./scripts/prow-smoke-test.sh -a openshift-acs "Red Hat Advanced Cluster Security" "4.10"

# Verify no inline Usage in CONCEPT modules (should return nothing)
for file in modules/roxctl-central*.adoc; do 
  if grep -q "CONCEPT" "$file" && grep -q "^\.Usage" "$file"; then 
    echo "❌ $file has inline Usage"
  fi
done

# Count abstracts (should match module count)
grep -c "^\[role=\"_abstract\"\]" modules/roxctl-central*.adoc

📝 Pre-Merge Checklist

All Netlify preview links functional
Build test passes cleanly
No CONCEPT modules with inline Usage/Options
"Options" terminology used (not "Flags")
All abstracts present
SME review complete (if required)
Cherrypick targets identified: rhacs-docs-4.10, rhacs-docs-4.9

Build status: ✅ Passing
DITA compliance: ✅ Met
Content integrity: ✅ Verified

agantony · 2026-07-22T16:55:58Z

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

PR: #111792
Jira: ROX-33164
Files Changed: 126 (1 assembly + 125 modules)
Line Changes: +1983 / -972
Preview: https://111792--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-central.html

===== SCENARIO 1: 2 REVIEWERS =====

Review Distribution

Reviewer	Scope	Files	%
Reviewer 1	generate, debug, userpki, backup, cert, whoami	64	51%
Reviewer 2	assembly + shared, db, init-bundles, crs, login	62	49%

Reviewer 1 — generate, debug, userpki, backup, cert, whoami (64 files)

generate (23 files) — Preview

debug (21 files) — Preview

userpki (11 files) — Preview

backup (3 files) — Preview

modules/roxctl-central-backup.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-backup-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-backup-options.adoc — REFERENCE: options table complete

cert (3 files) — Preview

modules/roxctl-central-cert.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-cert-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-cert-options.adoc — REFERENCE: options table complete

whoami (3 files) — Preview

modules/roxctl-central-whoami.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-whoami-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-whoami-options.adoc — REFERENCE: options table complete

Reviewer 1 Spot-Check Results

Abstracts present on all CONCEPT modules
No inline usage in CONCEPT modules (title + abstract only)
Syntax blocks present in all usage modules
Options tables complete in all options modules
Correct terminology ("Options" not "Flags") in all assigned modules
Content preserved from original (no lost rows in options tables)
Heading hierarchy correct (no level skips)
Netlify preview renders correctly for all assigned sections

Reviewer 2 — assembly + shared, db, init-bundles, crs, login (62 files)

assembly + shared (5 files) — Preview

cli/command-reference/roxctl-central.adoc — Assembly: verify all includes resolve, leveloffsets correct
modules/options-inherited-from-the-parent-command.adoc — Shared: verify reused correctly across includes
modules/roxctl-central-overview.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-available-commands.adoc — REFERENCE: available commands list complete

db (32 files) — Preview

init-bundles (13 files) — Preview

crs (9 files) — Preview

modules/roxctl-central-crs.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-generate.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-generate-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-generate-flags.adoc — FLAG: named "flags" not "options", verify if intentional
modules/roxctl-central-crs-list.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-list-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-revoke.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-revoke-usage.adoc — REFERENCE: syntax block present

login (3 files) — Preview

modules/roxctl-central-login.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-login-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-login-options.adoc — REFERENCE: options table complete

Reviewer 2 Spot-Check Results

All 126 include:: directives in assembly resolve correctly
Leveloffsets correct: +1 for parent commands, +2 for usage/options, +2 for subcommands, +3 for sub-usage/options
Shared module options-inherited-from-the-parent-command.adoc included at correct leveloffset in all locations
Abstracts present on all CONCEPT modules
No inline usage in CONCEPT modules (title + abstract only)
roxctl-central-crs-generate-flags.adoc — verify "flags" naming is intentional vs. "options"
Content preserved from original (no lost rows in options tables, no lost syntax)
Netlify preview renders correctly for all assigned sections
Navigation/TOC structure matches the intended 3-level hierarchy

===== SCENARIO 2: 3 REVIEWERS =====

Review Distribution

Reviewer	Scope	Files	%
Reviewer 1	db, crs	41	33%
Reviewer 2	assembly + shared, generate, userpki, login	42	33%
Reviewer 3	debug, init-bundles, backup, cert, whoami	43	34%

Reviewer 1 — db, crs (41 files)

db (32 files) — Preview

crs (9 files) — Preview

modules/roxctl-central-crs.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-generate.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-generate-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-generate-flags.adoc — FLAG: named "flags" not "options", verify if intentional
modules/roxctl-central-crs-list.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-list-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-crs-revoke.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-crs-revoke-usage.adoc — REFERENCE: syntax block present

Reviewer 1 Spot-Check Results

Abstracts present on all CONCEPT modules
No inline usage in CONCEPT modules (title + abstract only)
Syntax blocks present in all usage modules
Options tables complete in all options modules
roxctl-central-crs-generate-flags.adoc — verify "flags" naming is intentional vs. "options"
Content preserved from original (no lost rows in options tables)
Heading hierarchy correct (no level skips)
Netlify preview renders correctly for all assigned sections

Reviewer 2 — assembly + shared, generate, userpki, login (42 files)

assembly + shared (5 files) — Preview

cli/command-reference/roxctl-central.adoc — Assembly: verify all includes resolve, leveloffsets correct
modules/options-inherited-from-the-parent-command.adoc — Shared: verify reused correctly across includes
modules/roxctl-central-overview.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-available-commands.adoc — REFERENCE: available commands list complete

generate (23 files) — Preview

userpki (11 files) — Preview

login (3 files) — Preview

modules/roxctl-central-login.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-login-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-login-options.adoc — REFERENCE: options table complete

Reviewer 2 Spot-Check Results

All 126 include:: directives in assembly resolve correctly
Leveloffsets correct: +1 for parent commands, +2 for usage/options, +2 for subcommands, +3 for sub-usage/options
Shared module options-inherited-from-the-parent-command.adoc included at correct leveloffset in all locations
Abstracts present on all CONCEPT modules
No inline usage in CONCEPT modules (title + abstract only)
Content preserved from original (no lost rows in options tables)
Navigation/TOC structure matches the intended 3-level hierarchy
Netlify preview renders correctly for all assigned sections

Reviewer 3 — debug, init-bundles, backup, cert, whoami (43 files)

debug (21 files) — Preview

init-bundles (13 files) — Preview

backup (3 files) — Preview

modules/roxctl-central-backup.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-backup-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-backup-options.adoc — REFERENCE: options table complete

cert (3 files) — Preview

modules/roxctl-central-cert.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-cert-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-cert-options.adoc — REFERENCE: options table complete

whoami (3 files) — Preview

modules/roxctl-central-whoami.adoc — CONCEPT: title + abstract only, no inline usage
modules/roxctl-central-whoami-usage.adoc — REFERENCE: syntax block present
modules/roxctl-central-whoami-options.adoc — REFERENCE: options table complete

Reviewer 3 Spot-Check Results

Abstracts present on all CONCEPT modules
No inline usage in CONCEPT modules (title + abstract only)
Syntax blocks present in all usage modules
Options tables complete in all options modules
Correct terminology ("Options" not "Flags") in all assigned modules
Content preserved from original (no lost rows in options tables)
Heading hierarchy correct (no level skips)
Netlify preview renders correctly for all assigned sections

ROX33164 Fixing DITA errors in cli/command-reference/roxctl-central.adoc

dd6aa42

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label May 18, 2026

agantony added RHACS Label for RHACS related PRs that go in the rhacs-docs branch rhacs-docs-4.9 rhacs-docs-4.10 labels May 18, 2026

openshift-ci Bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label May 18, 2026

This was referenced May 18, 2026

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

Merged

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

Merged

ROX33164 Removing Usage information from the Concept modules

f859ebc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/command-reference/roxctl-central.adoc#111792
agantony wants to merge 2 commits into
openshift:rhacs-docs-mainfrom
agantony:ROX33164-dita-rework-installing-roxctl-central

agantony commented May 18, 2026

Uh oh!

openshift-ci-robot commented May 18, 2026 •

edited by openshift-ci Bot

Loading

Uh oh!

ocpdocs-previewbot commented May 18, 2026 •

edited

Loading

Uh oh!

openshift-ci Bot commented May 19, 2026

Uh oh!

agantony commented May 19, 2026 •

edited

Loading

Uh oh!

agantony commented Jul 22, 2026 •

edited by openshift-ci Bot

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

agantony commented May 18, 2026

Uh oh!

openshift-ci-robot commented May 18, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ocpdocs-previewbot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci Bot commented May 19, 2026

Uh oh!

agantony commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Review Guide: roxctl central CLI Reference Modularization

Summary

📊 Module Structure

Hierarchy Overview

Module Counts by Type

🔍 Step-by-Step Review Instructions

Netlify Preview Base

Review Sections

1️⃣ Assembly & Overview

2️⃣ Simple Parent Commands

3️⃣ Parent Commands with Sub-commands

✅ Verification Checklist

Structural Compliance

Content Integrity

Rendering Quality

🎯 Key Quality Standards Met

DITA Compliance

Content Quality

Build Quality

📋 Quick Visual Check Guide

✅ Correct Structure

❌ What to Watch For

🧪 Testing Commands

📝 Pre-Merge Checklist

Uh oh!

agantony commented Jul 22, 2026 • edited by openshift-ci Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

===== SCENARIO 1: 2 REVIEWERS =====

Review Distribution

Reviewer 1 — generate, debug, userpki, backup, cert, whoami (64 files)

generate (23 files) — Preview

debug (21 files) — Preview

userpki (11 files) — Preview

backup (3 files) — Preview

cert (3 files) — Preview

whoami (3 files) — Preview

Reviewer 1 Spot-Check Results

Reviewer 2 — assembly + shared, db, init-bundles, crs, login (62 files)

assembly + shared (5 files) — Preview

db (32 files) — Preview

init-bundles (13 files) — Preview

crs (9 files) — Preview

login (3 files) — Preview

Reviewer 2 Spot-Check Results

===== SCENARIO 2: 3 REVIEWERS =====

Review Distribution

Reviewer 1 — db, crs (41 files)

db (32 files) — Preview

crs (9 files) — Preview

Reviewer 1 Spot-Check Results

Reviewer 2 — assembly + shared, generate, userpki, login (42 files)

assembly + shared (5 files) — Preview

generate (23 files) — Preview

userpki (11 files) — Preview

login (3 files) — Preview

Reviewer 2 Spot-Check Results

Reviewer 3 — debug, init-bundles, backup, cert, whoami (43 files)

debug (21 files) — Preview

init-bundles (13 files) — Preview

backup (3 files) — Preview

cert (3 files) — Preview

whoami (3 files) — Preview

Reviewer 3 Spot-Check Results

Uh oh!

Reviewers

openshift-ci-robot commented May 18, 2026 •

edited by openshift-ci Bot

Loading

ocpdocs-previewbot commented May 18, 2026 •

edited

Loading

agantony commented May 19, 2026 •

edited

Loading

agantony commented Jul 22, 2026 •

edited by openshift-ci Bot

Loading