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

[agantony]

…ve-config.adoc

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:

…ve-config.adoc

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]

🤖 Sat May 16 12:40:29 - Prow CI generated the docs preview:
https://111775--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

[agantony]

📋 PR Review Summary

This PR fixes DITA compatibility errors in the roxctl declarative-config CLI reference by applying a large-scale modular refactoring following the pattern from PR #111737.

Changes Overview

Files Changed: 47 (31 new, 16 modified) | +748/-373 lines

What Changed

Every parent module with inline Usage/Options has been split into 3 modules:

1. Parent (CONCEPT) → Title + abstract only
2. Usage (REFERENCE) → Usage syntax
3. Options (REFERENCE) → Options table

Modules split:

• Assembly-level: 3 new modules (overview, usage, available-commands)
• Parent commands: 2 commands → 6 files (lint, create)
• Sub-commands: 12 commands → 36 files (role, notifier, access-scope, auth-provider, permission-set, + 7 auth-provider variants)

---

🔍 Step-by-Step Review Guide

Main Assembly Page

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html

Key checks:

• Assembly renders with complete 3-level hierarchy (H2 → H3 → H4)
• Assembly abstract displays correctly
• TOC shows all sections (overview → lint → create → 12 sub-commands)
• No broken includes or duplicate content

---

Assembly-Level Modules (3 new)

Overview (H2):

• Content: "Manage the declarative configuration."

Usage (H3):

• Syntax: $ roxctl declarative-config [command] [flags]

Available Commands (H3):

• Table with create and lint commands

---

Parent Commands (2 commands, 6 files)

1. roxctl declarative-config lint

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-lint_roxctl-declarative-config

• Renders as H2
• Abstract: "Lint an existing declarative configuration YAML file."
• Usage (H3) + Options (H3) subsections present
• Parent module has NO inline usage/options

2. roxctl declarative-config create

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-create_roxctl-declarative-config

• Renders as H2
• Abstract: "Create declarative configurations."
• Usage (H3) + Options (H3) subsections present
• 12 sub-commands render below as H3 sections

---

Sub-Commands (12 commands, 36 files)

Sample to review (spot-check 3-4):

create role

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-create-role_roxctl-declarative-config

• H3 under "create"
• Abstract: "Create a declarative configuration for a role."
• Usage (H4): $ roxctl declarative-config create role [flags]
• Options (H4): Includes --name, --access-scope, --permission-set

create access-scope

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-create-access-scope_roxctl-declarative-config

• H3 under "create"
• Abstract: "Create a declarative configuration for an access scope."
• Usage (H4) + Options (H4) with --cluster-label-selector, --namespace-label-selector

create auth-provider-oidc

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-create-auth-provider-oidc_roxctl-declarative-config

• H3 under "create"
• Abstract: "Create a declarative configuration for an OpenID Connect (OIDC) authentication provider."
• Options (H4): Includes --client-id, --client-secret, --issuer, --mode

create notifier-generic

📄 Preview: https://111775--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-declarative-config.html#roxctl-declarative-config-create-notifier-generic_roxctl-declarative-config

• H3 under "create"
• Abstract: "Create a declarative configuration for a generic notifier."
• Options (H4): Includes --webhook, --headers, --extra-fields

Remaining 8 sub-commands:

• create notifier
• create auth-provider
• create permission-set
• create notifier-splunk
• create auth-provider-iap
• create auth-provider-saml
• create auth-provider-userpki
• create auth-provider-openshift-auth

Spot-check 2-3 more to verify structure consistency.

---

✅ DITA Compliance Changes

Before	After
❌ Inline assembly content	✅ 3 assembly modules
❌ 14 REFERENCE parents with inline usage/options	✅ 14 CONCEPT parents (title + abstract)
❌ Missing usage modules	✅ 15 REFERENCE usage modules
❌ Missing options modules	✅ 16 REFERENCE options modules
⚠️ Mixed leveloffsets	✅ Consistent +1, +2, +3 hierarchy

---

✅ Fixed Issues

File: modules/options-inherited-from-the-parent-command.adoc

Whitespace issue - ✅ RESOLVED
Fixed missing space after comma in 11 instances:

-Alternatively,you can specify...
+Alternatively, you can specify...

All instances of "Alternatively," now have proper spacing.

---

🎯 Review Priority

Must Review

• ✅ Assembly renders with 3-level TOC
• ✅ All 31 new modules created
• ✅ All 14 parent modules converted to CONCEPT
• ✅ No content loss

Should Review

• ✅ Spot-check 4-5 sub-command pages
• ✅ Verify table rendering
• ✅ Check code block formatting

Nice to Review

• ✅ Whitespace issue ✅ FIXED
• ✅ Verify anchors work

---

📊 Structure Summary

roxctl declarative-config (assembly)
├── overview (CONCEPT, +1)
│   ├── usage (REFERENCE, +2)
│   └── available commands (REFERENCE, +2)
├── lint (CONCEPT, +1)
│   ├── usage (REFERENCE, +2)
│   └── options (REFERENCE, +2)
└── create (CONCEPT, +1)
    ├── usage (REFERENCE, +2)
    ├── options (REFERENCE, +2)
    └── [12 sub-commands] (CONCEPT, +2)
        ├── usage (REFERENCE, +3)
        └── options (REFERENCE, +3)

Total depth: 4 levels (assembly → parent → sub-command → usage/options)

---

📝 Full Review Guide

Comprehensive guide with all 47 files documented: [Available on request]

Copy to clipboard:

cat /tmp/pr-111775-review-guide.md | xclip -selection clipboard

---

Related: #111737 (pattern), #111774 (similar refactoring)

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