Revamp document generation ecosystem

Makefile

@@ -43,6 +43,7 @@ endef
 .PHONY: help default install fmt vet test importfmtlint golangcilint devcheck devchecknotest
 .PHONY: starttestcontainer removetestcontainer spincontainer openlocalwebapi openapp protogen
 .PHONY: _check_env _check_ping_env _check_docker _run_pf_container _wait_for_pf _stop_pf_container
+.PHONY: generate-options-docs generate-command-docs generate-all-docs
 
 # ====================================================================================
 # USER-FACING COMMANDS
@@ -83,6 +84,34 @@ golangcilint: ## Run golangci-lint for comprehensive code analysis
 	$(GOLANGCI_LINT) run --timeout 5m ./...
 	echo "✅ No linting issues found."
 
+generate-options-docs: ## Generate configuration options documentation then validate via golden tests
+	@echo "  > Docs: Generating options documentation..."
+	@if [ -z "$(OUTPUT)" ]; then \
+		mkdir -p ./docs/dev-ux-portal-docs/general; \
+		$(GOCMD) run ./tools/generate-options-docs -asciidoc -o ./docs/dev-ux-portal-docs/general/cli-configuration-settings-reference.adoc; \
+		echo "✅ Documentation generated at docs/dev-ux-portal-docs/general/cli-configuration-settings-reference.adoc"; \
+	else \
+		$(GOCMD) run ./tools/generate-options-docs $(OUTPUT); \
+		echo "✅ Documentation generated with custom OUTPUT $(OUTPUT)"; \
+	fi
+	@echo "  > Docs: Running golden tests for options docs..."
+	@$(GOCMD) test ./tools/generate-options-docs/docgen -run TestOptionsDocGeneration >/dev/null && echo "✅ Options documentation golden test passed."
+
+generate-command-docs: ## Generate per-command AsciiDoc pages then validate via golden tests
+	@echo "  > Docs: Generating command documentation..."
+	mkdir -p ./docs/dev-ux-portal-docs
+	$(GOCMD) run ./tools/generate-command-docs -o ./docs/dev-ux-portal-docs $(COMMAND_DOCS_ARGS)
+	echo "✅ Command docs generated in docs/dev-ux-portal-docs"
+	@echo "  > Docs: Running golden tests for command docs..."
+	@$(GOCMD) test ./tools/generate-command-docs -run TestCommandDocGeneration >/dev/null && echo "✅ Command documentation golden test passed."
+
+generate-all-docs: ## Rebuild ALL docs then run golden tests for both sets
+	@echo "  > Docs: Rebuilding all documentation (clean + regenerate)..."
+	mkdir -p ./docs/dev-ux-portal-docs/general
+	$(MAKE) generate-options-docs OUTPUT='-o docs/dev-ux-portal-docs/general/cli-configuration-settings-reference.adoc'
+	$(MAKE) generate-command-docs
+	@echo "✅ All documentation rebuilt and validated via golden tests."
+
 protogen: ## Generate Go code from .proto files
 	@echo "  > Protogen: Generating gRPC code from proto files..."
 	protoc --proto_path=./internal/proto --go_out=./internal --go-grpc_out=./internal ./internal/proto/*.proto

README.md

@@ -10,17 +10,17 @@ The Ping CLI is a unified command line interface for configuring and managing Pi
 ## Table of Contents
 
 - [Install](#install)
-	- [Docker](#docker)
-	- [macOS](#macos)
-	- [Linux](#linux)
-	- [Windows](#windows)
+  - [Docker](#docker)
+  - [macOS](#macos)
+  - [Linux](#linux)
+  - [Windows](#windows)
 - [Verify](#verify)
-	- [Checksums](#checksums)
-	- [GPG Signatures](#gpg-signatures)
+  - [Checksums](#checksums)
+  - [GPG Signatures](#gpg-signatures)
 - [Configure Ping CLI](#configure-ping-cli)
 - [Commands](#commands)
-	- [Platform Export](#platform-export)
-	- [Custom Request](#custom-request)
+  - [Platform Export](#platform-export)
+  - [Custom Request](#custom-request)
 - [Getting Help](#getting-help)
 
 ## Install
@@ -30,11 +30,13 @@ The Ping CLI is a unified command line interface for configuring and managing Pi
 Use the [Ping CLI Docker image](https://hub.docker.com/r/pingidentity/pingcli)
 
 Pull Image:
+
 ```shell
 docker pull pingidentity/pingcli:latest
 ```
 
 Example Commands:
+
 ```shell
 docker run --rm pingidentity/pingcli:latest <sub commands>
 
@@ -43,7 +45,7 @@ docker run --rm pingidentity/pingcli:latest --version
 
 ### macOS
 
-##### Homebrew
+#### Homebrew
 
 Use PingIdentity's Homebrew tap to install Ping CLI
 
@@ -52,7 +54,7 @@ brew tap pingidentity/tap
 brew install pingcli
 ```
 
-##### Manual Installation
+#### Manual Installation
 
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for artifact downloads, artifact signatures, and the checksum file. To verify package downloads, see the [Verify Section](#verify).
 
@@ -86,6 +88,7 @@ brew install pingcli
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for Alpine (.apk) package downloads. To verify package downloads, see the [Verify Section](#verify).
 
 > **_NOTE:_** The following commands may require `sudo` if not run as the root user.
+
 ```shell
 apk add --allow-untrusted ./pingcli_<version>_linux_amd64.apk
 apk add --allow-untrusted ./pingcli_<version>_linux_arm64.apk
@@ -96,6 +99,7 @@ apk add --allow-untrusted ./pingcli_<version>_linux_arm64.apk
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for Debian (.deb) package downloads. To verify package downloads, see the [Verify Section](#verify).
 
 > **_NOTE:_** The following commands may require `sudo` if not run as the root user.
+
 ```shell
 apt install ./pingcli_<version>_linux_amd64.deb
 apt install ./pingcli_<version>_linux_arm64.deb
@@ -106,6 +110,7 @@ apt install ./pingcli_<version>_linux_arm64.deb
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for RPM (.rpm) package downloads. To verify package downloads, see the [Verify Section](#verify).
 
 > **_NOTE:_** The following commands may require `sudo` if not run as the root user.
+
 ```shell
 yum install ./pingcli_<version>_linux_amd64.rpm
 yum install ./pingcli_<version>_linux_arm64.rpm
@@ -114,17 +119,19 @@ yum install ./pingcli_<version>_linux_arm64.rpm
 OR
 
 > **_NOTE:_** The following commands may require `sudo` if not run as the root user.
+
 ```shell
 dnf install ./pingcli_<version>_linux_amd64.rpm
 dnf install ./pingcli_<version>_linux_arm64.rpm
 ```
 
 > **_NOTE:_**
+
 > - Use `yum` for CentOS/RHEL 7 and earlier, and for older Fedora systems.
 > - Use `dnf` for Fedora 22+ and CentOS/RHEL 8+.
 > Both commands achieve the same result; use the one appropriate for your distribution.
 
-##### Manual Installation
+#### Manual Installation
 
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for artifact downloads, artifact signatures, and the checksum file. To verify package downloads, see the [Verify Section](#verify).
 
@@ -144,14 +151,15 @@ sudo mv pingcli /usr/local/bin/pingcli;
 
 ### Windows
 
-##### Manual Installation
+#### Manual Installation
 
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for artifact downloads, artifact signatures, and the checksum file. To verify package downloads, see the [Verify Section](#verify).
 
 OR
 
 Use the following single-line PowerShell 7.4 command to install Ping CLI into '%LOCALAPPDATA%\Programs' directly.
 >**_NOTE:_** After installation, ensure that `%LOCALAPPDATA%\Programs` is included in your PATH environment variable. If it is not already present, add it so you can call `pingcli` directly in your terminal.
+
 ```powershell
 $latestReleaseUrl = Invoke-WebRequest -Uri "https://github.com/pingidentity/pingcli/releases/latest" -MaximumRedirection 0 -ErrorAction Ignore -UseBasicParsing -SkipHttpErrorCheck; `
 $RELEASE_VERSION = [System.IO.Path]::GetFileName($latestReleaseUrl.Headers.Location); `
@@ -172,7 +180,7 @@ See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases
 
 See [the latest GitHub release](https://github.com/pingidentity/pingcli/releases/latest) for the artifact downloads and signature files.
 
-##### Add our public GPG Key via OpenPGP Public Key Server
+#### Add our public GPG Key via OpenPGP Public Key Server
 
 ```shell
 gpg --keyserver keys.openpgp.org --recv-key 0x6703FFB15B36A7AC
@@ -181,6 +189,7 @@ gpg --keyserver keys.openpgp.org --recv-key 0x6703FFB15B36A7AC
 OR
 
 ##### Add our public GPG Key via MIT PGP Public Key Server
+
 ```shell
 gpg --keyserver pgp.mit.edu --recv-key 0x6703FFB15B36A7AC
 ```
@@ -216,6 +225,12 @@ and their purposes.
 
 See [Autocompletion Documentation](./docs/autocompletion/autocompletion.md) for information on loading autocompletion for select command flags.
 
+### Documentation Generation
+
+Documentation generation instructions (configuration options reference, per-command pages, navigation, rebuild workflow, and golden test usage) have moved to a dedicated guide:
+
+See: `tools/README_DocumentGeneration.md`
+
 ## Commands
 
 Ping CLI commands have the following structure:

docs/dev-ux-portal-docs/general/cli-configuration-settings-reference.adoc

@@ -0,0 +1,87 @@
+= Configuration Settings Reference
+:created-date: March 23, 2025
+:revdate: September 24, 2025
+:resourceid: pingcli_configuration_settings_reference
+
+The following configuration settings can be applied when using Ping CLI.
+
+The following configuration settings can be applied by using the xref:command_reference:pingcli_config_set.adoc[`config set` command] to persist the configuration value for a given **Configuration Key** in the Ping CLI configuration file.
+
+The configuration file is created at `.pingcli/config.yaml` in the user's home directory.
+
+== General Properties
+
+[cols="2,2,2,1,3"]
+|===
+|Configuration Key |Equivalent Parameter |Environment Variable |Data Type |Purpose
+
+| `activeProfile` |  |  | String | 
+| `description` |  |  | String | 
+| `detailedExitCode` | `--detailed-exitcode` / `-D` | PINGCLI_DETAILED_EXITCODE | Boolean | Enable detailed exit code output. (default false) 0 - pingcli command succeeded with no errors or warnings. 1 - pingcli command failed with errors. 2 - pingcli command succeeded with warnings.
+| `noColor` | `--no-color` | PINGCLI_NO_COLOR | Boolean | Disable text output in color. (default false)
+| `outputFormat` | `--output-format` / `-O` | PINGCLI_OUTPUT_FORMAT | String (Enum) | Specify the console output format. (default text) Options are: json, text.
+| `plugins` |  |  | String Array | 
+|===
+
+== Ping Identity Platform Service Properties
+
+[cols="2,2,2,1,3"]
+|===
+|Configuration Key |Equivalent Parameter |Environment Variable |Data Type |Purpose
+
+| `service.pingfederate.adminAPIPath` | `--pingfederate-admin-api-path` | PINGCLI_PINGFEDERATE_ADMIN_API_PATH | String | The PingFederate API URL path used to communicate with PingFederate's admin API. (default /pf-admin-api/v1)
+| `service.pingfederate.authentication.accessTokenAuth.accessToken` | `--pingfederate-access-token` | PINGCLI_PINGFEDERATE_ACCESS_TOKEN | String | The PingFederate access token used to authenticate to the PingFederate admin API when using a custom OAuth 2.0 token method.
+| `service.pingfederate.authentication.basicAuth.password` | `--pingfederate-password` | PINGCLI_PINGFEDERATE_PASSWORD | String | The PingFederate password used to authenticate to the PingFederate admin API when using basic authentication.
+| `service.pingfederate.authentication.basicAuth.username` | `--pingfederate-username` | PINGCLI_PINGFEDERATE_USERNAME | String | The PingFederate username used to authenticate to the PingFederate admin API when using basic authentication. Example: 'administrator'
+| `service.pingfederate.authentication.clientCredentialsAuth.clientID` | `--pingfederate-client-id` | PINGCLI_PINGFEDERATE_CLIENT_ID | String | The PingFederate OAuth client ID used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type.
+| `service.pingfederate.authentication.clientCredentialsAuth.clientSecret` | `--pingfederate-client-secret` | PINGCLI_PINGFEDERATE_CLIENT_SECRET | String | The PingFederate OAuth client secret used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type.
+| `service.pingfederate.authentication.clientCredentialsAuth.scopes` | `--pingfederate-scopes` | PINGCLI_PINGFEDERATE_SCOPES | String Array | The PingFederate OAuth scopes used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type. (default []) Accepts a comma-separated string to delimit multiple scopes. Example: 'openid,profile'
+| `service.pingfederate.authentication.clientCredentialsAuth.tokenURL` | `--pingfederate-token-url` | PINGCLI_PINGFEDERATE_TOKEN_URL | String | The PingFederate OAuth token URL used to authenticate to the PingFederate admin API when using the OAuth 2.0 client credentials grant type.
+| `service.pingfederate.authentication.type` | `--pingfederate-authentication-type` | PINGCLI_PINGFEDERATE_AUTHENTICATION_TYPE | String (Enum) | The authentication type to use when connecting to the PingFederate admin API. Options are: accessTokenAuth, basicAuth, clientCredentialsAuth. Example: 'basicAuth'
+| `service.pingfederate.caCertificatePemFiles` | `--pingfederate-ca-certificate-pem-files` | PINGCLI_PINGFEDERATE_CA_CERTIFICATE_PEM_FILES | String Array | Relative or full paths to PEM-encoded certificate files to be trusted as root CAs when connecting to the PingFederate server over HTTPS. (default []) Accepts a comma-separated string to delimit multiple PEM files.
+| `service.pingfederate.httpsHost` | `--pingfederate-https-host` | PINGCLI_PINGFEDERATE_HTTPS_HOST | String | The PingFederate HTTPS host used to communicate with PingFederate's admin API. Example: 'https://pingfederate-admin.bxretail.org'
+| `service.pingfederate.insecureTrustAllTLS` | `--pingfederate-insecure-trust-all-tls` | PINGCLI_PINGFEDERATE_INSECURE_TRUST_ALL_TLS | Boolean | Trust any certificate when connecting to the PingFederate server admin API. (default false) This is insecure and shouldn't be enabled outside of testing.
+| `service.pingfederate.xBypassExternalValidationHeader` | `--pingfederate-x-bypass-external-validation-header` | PINGCLI_PINGFEDERATE_X_BYPASS_EXTERNAL_VALIDATION_HEADER | Boolean | Bypass connection tests when configuring PingFederate (the X-BypassExternalValidation header when using PingFederate's admin API). (default false)
+| `service.pingone.authentication.type` | `--pingone-authentication-type` | PINGCLI_PINGONE_AUTHENTICATION_TYPE | String (Enum) | The authentication type to use to authenticate to the PingOne management API. (default worker) Options are: worker.
+| `service.pingone.authentication.worker.clientID` | `--pingone-worker-client-id` | PINGCLI_PINGONE_WORKER_CLIENT_ID | String (UUID Format) | The worker client ID used to authenticate to the PingOne management API.
+| `service.pingone.authentication.worker.clientSecret` | `--pingone-worker-client-secret` | PINGCLI_PINGONE_WORKER_CLIENT_SECRET | String | The worker client secret used to authenticate to the PingOne management API.
+| `service.pingone.authentication.worker.environmentID` | `--pingone-worker-environment-id` | PINGCLI_PINGONE_WORKER_ENVIRONMENT_ID | String (UUID Format) | The ID of the PingOne environment that contains the worker client used to authenticate to the PingOne management API.
+| `service.pingone.regionCode` | `--pingone-region-code` | PINGCLI_PINGONE_REGION_CODE | String (Enum) | The region code of the PingOne tenant. Options are: AP, AU, CA, EU, NA. Example: 'NA'
+|===
+
+== Platform Export Properties
+
+[cols="2,2,2,1,3"]
+|===
+|Configuration Key |Equivalent Parameter |Environment Variable |Data Type |Purpose
+
+| `export.format` | `--format` / `-f` | PINGCLI_EXPORT_FORMAT | String (Enum) | Specifies the export format. (default HCL) Options are: HCL.
+| `export.outputDirectory` | `--output-directory` / `-d` | PINGCLI_EXPORT_OUTPUT_DIRECTORY | String | Specifies the output directory for export. Can be an absolute filepath or a relative filepath of the present working directory.  Example: '/Users/example/pingcli-export' Example: 'pingcli-export'
+| `export.overwrite` | `--overwrite` / `-o` | PINGCLI_EXPORT_OVERWRITE | Boolean | Overwrites the existing generated exports in output directory. (default false)
+| `export.pingone.environmentID` | `--pingone-export-environment-id` | PINGCLI_PINGONE_EXPORT_ENVIRONMENT_ID | String (UUID Format) | The ID of the PingOne environment to export. Must be a valid PingOne UUID.
+| `export.serviceGroup` | `--service-group` / `-g` | PINGCLI_EXPORT_SERVICE_GROUP | String (Enum) | Specifies the service group to export.  Options are: pingone. Example: 'pingone'
+| `export.services` | `--services` / `-s` | PINGCLI_EXPORT_SERVICES | String Array | Specifies the service(s) to export. Accepts a comma-separated string to delimit multiple services.  Options are: pingfederate, pingone-authorize, pingone-mfa, pingone-platform, pingone-protect, pingone-sso. Example: 'pingone-sso,pingone-mfa,pingfederate'
+|===
+
+== License Properties
+
+[cols="2,2,2,1,3"]
+|===
+|Configuration Key |Equivalent Parameter |Environment Variable |Data Type |Purpose
+
+| `license.devopsKey` | `--devops-key` / `-k` | PINGCLI_LICENSE_DEVOPS_KEY | String | The DevOps key for the license request.   See https://developer.pingidentity.com/devops/how-to/devopsRegistration.html on how to register a DevOps user.   You can save the DevOps user and key in your profile using the 'pingcli config' commands.
+| `license.devopsUser` | `--devops-user` / `-u` | PINGCLI_LICENSE_DEVOPS_USER | String | The DevOps user for the license request.   See https://developer.pingidentity.com/devops/how-to/devopsRegistration.html on how to register a DevOps user.   You can save the DevOps user and key in your profile using the 'pingcli config' commands.
+|===
+
+== Custom Request Properties
+
+[cols="2,2,2,1,3"]
+|===
+|Configuration Key |Equivalent Parameter |Environment Variable |Data Type |Purpose
+
+| `request.accessToken` |  |  | String | 
+| `request.accessTokenExpiry` |  |  | Integer | 
+| `request.fail` | `--fail` / `-f` |  | Boolean | Return non-zero exit code when HTTP custom request returns a failure status code.
+| `request.service` | `--service` / `-s` | PINGCLI_REQUEST_SERVICE | String (Enum) | The Ping service (configured in the active profile) to send the custom request to. Options are: pingone. Example: 'pingone'
+|===
+

docs/dev-ux-portal-docs/nav.adoc

@@ -0,0 +1,23 @@
+* Command Reference
+** xref:command_reference:pingcli.adoc[]
+** xref:command_reference:pingcli_completion.adoc[]
+** xref:command_reference:pingcli_config.adoc[]
+*** xref:command_reference:pingcli_config_add-profile.adoc[]
+*** xref:command_reference:pingcli_config_delete-profile.adoc[]
+*** xref:command_reference:pingcli_config_get.adoc[]
+*** xref:command_reference:pingcli_config_list-keys.adoc[]
+*** xref:command_reference:pingcli_config_list-profiles.adoc[]
+*** xref:command_reference:pingcli_config_set.adoc[]
+*** xref:command_reference:pingcli_config_set-active-profile.adoc[]
+*** xref:command_reference:pingcli_config_unset.adoc[]
+*** xref:command_reference:pingcli_config_view-profile.adoc[]
+** xref:command_reference:pingcli_feedback.adoc[]
+** xref:command_reference:pingcli_license.adoc[]
+** xref:command_reference:pingcli_platform.adoc[]
+*** xref:command_reference:pingcli_platform_export.adoc[]
+** xref:command_reference:pingcli_plugin.adoc[]
+*** xref:command_reference:pingcli_plugin_add.adoc[]
+*** xref:command_reference:pingcli_plugin_list.adoc[]
+*** xref:command_reference:pingcli_plugin_remove.adoc[]
+** xref:command_reference:pingcli_request.adoc[]
+