fix: apply all downstream requirements

Author: wtrocki

.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/github-pages-deploy-action@4.1.8
         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.

Makefile

@@ -85,9 +85,14 @@ 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-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
 	app-services-go-linter ./...

internal/doc/GeneratorOptions.go

@@ -20,5 +20,5 @@ type GeneratorOptions struct {
 	GenerateIndex bool
 
 	// IndexLocation - name and folder of the assembly file (typically ./README.adoc)
-	IndexLocation string
+	IndexFile string
 }

internal/doc/docs_index.go

@@ -2,6 +2,8 @@ package doc
 
 import (
 	"os"
+	"path"
+	"path/filepath"
 	"text/template"
 
 	"github.com/pkg/errors"
@@ -64,7 +66,7 @@ func CreateIndexFile(rootCmd *cobra.Command, generationOptions *GeneratorOptions
 		Groups: groups,
 	}
 
-	output, err := os.Create(generationOptions.IndexLocation)
+	output, err := os.Create(generationOptions.IndexFile)
 	if err != nil {
 		return errors.WithStack(err)
 	}
@@ -83,6 +85,11 @@ func CreateIndexFile(rootCmd *cobra.Command, generationOptions *GeneratorOptions
 
 func CollectNames(cmd *cobra.Command, options *GeneratorOptions) []string {
 	filename := options.FileNameGenerator(cmd)
+
+	filename, err := filepath.Rel(path.Dir(options.IndexFile), filename)
+	if err != nil {
+		panic(err)
+	}
 	names := []string{filename}
 	if cmd.HasSubCommands() {
 		for _, sub := range cmd.Commands() {

internal/doc/modular_adoc_docs.go

@@ -322,7 +322,7 @@ func GenAsciidocTree(cmd *cobra.Command, options *GeneratorOptions) error {
 		return err
 	}
 
-	if options.GenerateIndex && options.IndexLocation != "" {
+	if options.GenerateIndex && options.IndexFile != "" {
 		return CreateIndexFile(cmd, options)
 	}
 	return nil

pkg/cmd/docs/docs.go

@@ -2,6 +2,9 @@ package docs
 
 import (
 	"fmt"
+	"os"
+	"path"
+	"path/filepath"
 	"time"
 
 	rhoasdoc "github.com/redhat-developer/app-services-cli/internal/doc"
@@ -18,10 +21,10 @@ const (
 )
 
 type options struct {
-	dir    string
-	format string
-
-	logger logging.Logger
+	dir        string
+	format     string
+	filePrefix string
+	logger     logging.Logger
 }
 
 // NewDocsCmd creates a new docs command
@@ -42,6 +45,7 @@ func NewDocsCmd(f *factory.Factory) *cobra.Command {
 
 	cmd.Flags().StringVar(&opts.format, "file-format", "md", "Output format of the generated documentation. Valid options are: 'md' (markdown), 'adoc' (Asciidoc) and 'man'")
 	cmd.Flags().StringVar(&opts.dir, "dir", "./docs", "The directory to output the generated documentation files")
+	cmd.Flags().StringVar(&opts.filePrefix, "file-prefix", "ref-", "Prefix for each documentation file")
 	return cmd
 }
 
@@ -60,10 +64,28 @@ func runCmd(cmd *cobra.Command, opts *options) (err error) {
 		}
 		err = doc.GenManTree(cmd.Root(), header, opts.dir)
 	case asciidoc:
-		err = rhoasdoc.GenAsciidocTree(cmd.Root(), &rhoasdoc.GeneratorOptions{
-			Dir:           opts.dir,
+		docsDir := path.Clean(opts.dir + "/modules")
+		assembliesDir := path.Clean(opts.dir + "/assemblies")
+		err = os.MkdirAll(docsDir, 0755)
+		if err != nil {
+			return err
+		}
+		err = os.MkdirAll(assembliesDir, 0755)
+		if err != nil {
+			return err
+		}
+
+		options := rhoasdoc.GeneratorOptions{
+			Dir:           docsDir,
 			GenerateIndex: true,
-			IndexLocation: opts.dir + "/README.adoc"})
+			IndexFile:     assembliesDir + "/assembly-cli-command-reference.adoc"}
+
+		options.FileNameGenerator = func(c *cobra.Command) string {
+			basename := opts.filePrefix + rhoasdoc.GetNormalizedCommandPath(c) + ".adoc"
+			return filepath.Join(options.Dir, basename)
+		}
+
+		err = rhoasdoc.GenAsciidocTree(cmd.Root(), &options)
 	}
 
 	if err != nil {