Future Documentation workflow

.github/workflows/modular-docs-publish.yml

@@ -1,10 +1,16 @@
 # This workflow will generate modular docs and publish to the modular-docs branch
 
-name: Modular docs publish
+name: Downstream docs publish
 
+# on:
+#   push:
+#     tags:
+#       - 'v*'
+
+## For testing
 on:
   push:
-    branches: [ main ]
+    branches: [ adoc-modular ]
 
 jobs:
   build:
@@ -16,10 +22,10 @@ jobs:
         uses: actions/setup-go@v2
         with:
           go-version: 1.16.x
-      - run: make generate-modular-docs
-        name: Generate modular-docs
+      - run: make generate-downstream-docs
+        name: Generate generate-downstream-docs
       - name: Deploy
         uses: JamesIves/[email protected]
         with:
-          branch: modular-docs # The branch the action should deploy to.
+          branch: downstream-docs # The branch the action should deploy to.
           folder: dist # The folder the action should deploy.

.vscode/launch.json

@@ -268,5 +268,18 @@
         "--yes"
       ]
     },
+    {
+      "name": "Docs",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/rhoas",
+      "env": {},
+      "args": [
+        "docs",
+        "--file-format", "adoc",
+        "--dir", "./docs/commands"
+      ]
+    },
   ]
 }

Makefile

@@ -85,12 +85,13 @@ check-docs: generate-docs ## Check whether reference documentation needs to be g
 
 generate-docs: ## Generate command-line reference documentation
 	rm -rf ./docs/commands/*
-	go run ./cmd/rhoas docs --dir ./docs/commands --file-format adoc
+	go run ./cmd/rhoas docs --dir ./docs/commands --file-format md
 .PHONY: generate-docs
 
-generate-modular-docs: generate-docs ## Generate modular command-line reference documentation
-	SRC_DIR=$$(pwd)/docs/commands DEST_DIR=$$(pwd)/dist go run ./cmd/modular-docs
-.PHONY: generate-modular-docs
+generate-downstream-docs: ## Generate command-line reference documentation in adoc format
+	rm -rf ./docs/commands/*
+	go run ./cmd/rhoas docs --dir ./dist --file-format adoc
+.PHONY: generate-downstream-docs
 
 lint-lang: ## Lint i18n files
 	go install github.com/redhat-developer/app-services-go-linter/cmd/app-services-go-linter@latest

docs/commands/rhoas.md

@@ -0,0 +1,48 @@
+## rhoas
+
+RHOAS CLI
+
+### Synopsis
+
+Red Hat OpenShift Application Services
+
+Manage your application services from the command line. You can manage service accounts, Kafka instances, and Service Registry instances, and connect them to your OpenShift clusters and applications.
+
+
+### Examples
+
+```
+# Authenticate securely through your web browser
+$ rhoas login
+
+# Create a Kafka instance
+$ rhoas kafka create --name my-kafka-instance
+
+# Create a service account and save credentials to a JSON file
+$ rhoas service-account create -o json
+
+# Connect your Kubernetes/OpenShift cluster to a service
+$ rhoas cluster connect
+
+```
+
+### Options
+
+```
+  -h, --help      Show help for a command
+  -v, --verbose   Enable verbose mode
+      --version   Show rhoas version
+```
+
+### SEE ALSO
+
+* [rhoas cluster](rhoas_cluster.md)	 - View and perform operations on your Kubernetes or OpenShift cluster
+* [rhoas completion](rhoas_completion.md)	 - Install command completion for your shell (bash, zsh, or fish)
+* [rhoas kafka](rhoas_kafka.md)	 - Create, view, use, and manage your Kafka instances
+* [rhoas login](rhoas_login.md)	 - Log in to RHOAS
+* [rhoas logout](rhoas_logout.md)	 - Log out from RHOAS
+* [rhoas service-account](rhoas_service-account.md)	 - Create, list, describe, delete, and update service accounts
+* [rhoas service-registry](rhoas_service-registry.md)	 - Service Registry commands
+* [rhoas status](rhoas_status.md)	 - View the status of your application services
+* [rhoas whoami](rhoas_whoami.md)	 - Output the current username
+

docs/commands/rhoas_cluster.md

@@ -0,0 +1,43 @@
+## rhoas cluster
+
+View and perform operations on your Kubernetes or OpenShift cluster
+
+### Synopsis
+
+Connect and bind your services to Kubernetes or OpenShift applications. You can also check if the Kubernetes or OpenShift cluster has the required Operators to perform this operation.
+
+### Examples
+
+```
+# Check the status of the connection to your cluster
+$ rhoas cluster status
+
+# Connect to cluster without including currently selected services
+$ rhoas cluster connect --ignore-context
+
+# Connect to cluster using the specified token
+$ rhoas cluster connect --token=value
+
+# Connect to cluster and save script to create service binding
+$ rhoas cluster connect --yes > create_service_binding.sh
+
+# Connect managed service with your application
+$ rhoas cluster bind
+
+```
+
+### Options inherited from parent commands
+
+```
+  -h, --help      Show help for a command
+  -v, --verbose   Enable verbose mode
+```
+
+### SEE ALSO
+
+* [rhoas](rhoas.md)	 - RHOAS CLI
+* [rhoas cluster bind](rhoas_cluster_bind.md)	 - Connect your RHOAS services to Kubernetes or OpenShift applications
+* [rhoas cluster clean](rhoas_cluster_clean.md)	 - Remove all resources created by cluster extensions
+* [rhoas cluster connect](rhoas_cluster_connect.md)	 - Connect your services to Kubernetes or OpenShift
+* [rhoas cluster status](rhoas_cluster_status.md)	 - View the status of the current Kubernetes or OpenShift cluster
+