Improve docs on Supported Resources (Azure#2339)

hack/crossplane/apis/resources.md

@@ -1,8 +1,9 @@
 ---
 title: Supported Resources
 ---
+These are the Crossplane resources committed to our **main** branch, grouped by the originating ARM service.
+(Newly supported resources will appear in this list prior to inclusion in any ASO release.)
 
-These are the resources with Azure Service Operator support committed to our **main** branch, grouped by the originating ARM service. (Newly supported resources will appear in this list prior to inclusion in any ASO release.)
 
 ## Cache
 

hack/crossplane/azure-crossplane.yaml

@@ -5,6 +5,14 @@ schemaUrlRewrite:
 destinationGoModuleFile: go.mod
 # These two paths are relative to the module path above.
 typesOutputPath: apis
+
+supportedResourcesReport:
+  # Path is relative to the module path, above
+  outputPath: apis/resources.md
+  introduction: |
+    These are the Crossplane resources committed to our **main** branch, grouped by the originating ARM service.
+    (Newly supported resources will appear in this list prior to inclusion in any ASO release.)
+
 pipeline: crossplane
 typeFilters:
   - action: prune

v2/azure-arm.yaml

@@ -19,6 +19,14 @@ emitDocFiles: true
 
 pipeline: azure
 
+supportedResourcesReport:
+  # Path is relative to the module path, above
+  outputPath: ../docs/hugo/content/reference/_index.md
+  introduction: |
+    These are the resources with Azure Service Operator support committed to our **main** branch
+    grouped by the originating ARM service.
+    (Newly supported resources will appear in this list prior to inclusion in any ASO release.)
+
 #
 # These filters are used early in the processing pipeline. 
 #

v2/tools/generator/internal/codegen/pipeline/report_resource_versions.go

@@ -10,12 +10,12 @@ import (
 	"fmt"
 	"io/ioutil"
 	"os"
-	"path"
 	"sort"
 	"strings"
 
 	"github.com/pkg/errors"
 	kerrors "k8s.io/apimachinery/pkg/util/errors"
+	"k8s.io/klog/v2"
 
 	"github.com/Azure/azure-service-operator/v2/internal/set"
 
@@ -33,9 +33,9 @@ func ReportResourceVersions(configuration *config.Configuration) *Stage {
 		ReportResourceVersionsStageID,
 		"Generate a report listing all the resources generated",
 		func(ctx context.Context, state *State) (*State, error) {
-			report := NewResourceVersionsReport(state.Definitions(), configuration.ObjectModelConfiguration)
+			report := NewResourceVersionsReport(state.Definitions(), configuration)
 
-			err := report.WriteTo(configuration.FullTypesOutputPath(), configuration.SamplesURL)
+			err := report.WriteTo(configuration.SupportedResourcesReport.FullOutputPath())
 			if err != nil {
 				return nil, err
 			}
@@ -46,19 +46,24 @@ func ReportResourceVersions(configuration *config.Configuration) *Stage {
 }
 
 type ResourceVersionsReport struct {
+	reportConfiguration      *config.SupportedResourcesReport
 	objectModelConfiguration *config.ObjectModelConfiguration
+	samplesUrl               string
 	groups                   set.Set[string]                       // A set of all our groups
 	kinds                    map[string]astmodel.TypeDefinitionSet // For each group, the set of all available resources
+	frontMatter              string                                // Front matter to be inserted at the top of the report
 	// A separate list of resources for each package
 	lists map[astmodel.PackageReference][]astmodel.TypeDefinition
 }
 
 func NewResourceVersionsReport(
 	definitions astmodel.TypeDefinitionSet,
-	cfg *config.ObjectModelConfiguration,
+	cfg *config.Configuration,
 ) *ResourceVersionsReport {
 	result := &ResourceVersionsReport{
-		objectModelConfiguration: cfg,
+		reportConfiguration:      cfg.SupportedResourcesReport,
+		objectModelConfiguration: cfg.ObjectModelConfiguration,
+		samplesUrl:               cfg.SamplesURL,
 		groups:                   set.Make[string](),
 		kinds:                    make(map[string]astmodel.TypeDefinitionSet),
 		lists:                    make(map[astmodel.PackageReference][]astmodel.TypeDefinition),
@@ -94,40 +99,46 @@ func (report *ResourceVersionsReport) summarize(definitions astmodel.TypeDefinit
 }
 
 // WriteTo creates a file containing the generated report
-func (report *ResourceVersionsReport) WriteTo(outputPath string, samplesURL string) error {
+func (report *ResourceVersionsReport) WriteTo(outputFile string) error {
+
+	klog.V(1).Infof("Writing report to %s", outputFile)
+	report.frontMatter = report.readFrontMatter(outputFile)
+
 	var buffer strings.Builder
-	err := report.WriteToBuffer(&buffer, samplesURL)
+	err := report.WriteToBuffer(&buffer)
 	if err != nil {
-		return errors.Wrapf(err, "writing versions report to %s", outputPath)
+		return errors.Wrapf(err, "writing versions report to %s", outputFile)
 	}
 
-	if _, err := os.Stat(outputPath); os.IsNotExist(err) {
-		err = os.MkdirAll(outputPath, 0o700)
+	if _, err := os.Stat(outputFile); os.IsNotExist(err) {
+		err = os.MkdirAll(outputFile, 0o700)
 		if err != nil {
-			return errors.Wrapf(err, "Unable to create directory %q", outputPath)
+			return errors.Wrapf(err, "Unable to create directory %q", outputFile)
 		}
 	}
 
-	destination := path.Join(outputPath, "resources.md")
-	return ioutil.WriteFile(destination, []byte(buffer.String()), 0o600)
+	return ioutil.WriteFile(outputFile, []byte(buffer.String()), 0o600)
 }
 
 // WriteToBuffer creates the report in the provided buffer
-func (report *ResourceVersionsReport) WriteToBuffer(buffer *strings.Builder, samplesURL string) error {
-	buffer.WriteString("---\n")
-	buffer.WriteString("title: Supported Resources\n")
-	buffer.WriteString("---\n\n")
-	buffer.WriteString("These are the resources with Azure Service Operator support committed to our **main** branch, ")
-	buffer.WriteString("grouped by the originating ARM service. ")
-	buffer.WriteString("(Newly supported resources will appear in this list prior to inclusion in any ASO release.)\n\n")
+func (report *ResourceVersionsReport) WriteToBuffer(buffer *strings.Builder) error {
+
+	if report.frontMatter != "" {
+		buffer.WriteString(report.frontMatter)
+	} else {
+		buffer.WriteString(report.defaultFrontMatter())
+	}
+
+	buffer.WriteString(report.reportConfiguration.Introduction)
+	buffer.WriteString("\n\n")
 
 	// Sort groups into alphabetical order
 	groups := set.AsSortedSlice(report.groups)
 
 	var errs []error
 	for _, svc := range groups {
 		buffer.WriteString(fmt.Sprintf("## %s\n\n", strings.Title(svc)))
-		table, err := report.createTable(report.kinds[svc], svc, samplesURL)
+		table, err := report.createTable(report.kinds[svc], svc, report.samplesUrl)
 		if err != nil {
 			errs = append(errs, err)
 			continue
@@ -229,3 +240,41 @@ func (report *ResourceVersionsReport) generateSupportedFrom(typeName astmodel.Ty
 
 	return supportedFrom, nil
 }
+
+// Read in any front matter present in our output file, so we preserve it when writing out the new file.
+// Returns an empty string if the file doesn't exist
+func (report *ResourceVersionsReport) readFrontMatter(outputPath string) string {
+
+	if _, err := os.Stat(outputPath); os.IsNotExist(err) {
+		return ""
+	}
+
+	klog.V(2).Infof("Reading front matter from %s", outputPath)
+	data, err := ioutil.ReadFile(outputPath)
+	if err != nil {
+		return ""
+	}
+
+	var buffer strings.Builder
+
+	// Copy until we find the end of the frontmatter
+	for index, line := range strings.Split(string(data), "\n") {
+		buffer.WriteString(line)
+		buffer.WriteString("\n")
+		if index >= 2 && strings.HasPrefix(line, "---") {
+			break
+		}
+	}
+
+	return buffer.String()
+}
+
+// defaultFrontMatter returns the default front-matter for the report if no existing file is present,
+// or if it has no front-matter present.
+func (report *ResourceVersionsReport) defaultFrontMatter() string {
+	var buffer strings.Builder
+	buffer.WriteString("---\n")
+	buffer.WriteString("title: Supported Resources\n")
+	buffer.WriteString("---\n\n")
+	return buffer.String()
+}

v2/tools/generator/internal/codegen/pipeline/report_resource_versions_test.go

@@ -59,45 +59,31 @@ func TestGolden_ReportResourceVersions(t *testing.T) {
 	defs := make(astmodel.TypeDefinitionSet)
 	defs.AddAll(person2020, address2020, person2021, address2021)
 
-	cfg := config.NewObjectModelConfiguration()
-	g.Expect(
-		cfg.ModifyType(
-			person2020.Name(),
-			func(tc *config.TypeConfiguration) error {
-				tc.SetSupportedFrom("beta.0")
-				return nil
-			})).
-		To(Succeed())
-	g.Expect(
-		cfg.ModifyType(
-			address2020.Name(),
-			func(tc *config.TypeConfiguration) error {
-				tc.SetSupportedFrom("beta.0")
-				return nil
-			})).
-		To(Succeed())
-	g.Expect(
-		cfg.ModifyType(
-			person2021.Name(),
-			func(tc *config.TypeConfiguration) error {
-				tc.SetSupportedFrom("beta.2")
-				return nil
-			})).
-		To(Succeed())
-	g.Expect(
-		cfg.ModifyType(
-			address2021.Name(),
-			func(tc *config.TypeConfiguration) error {
-				tc.SetSupportedFrom("beta.2")
-				return nil
-			})).
-		To(Succeed())
+	// utility function used to configure a which ASO version from which a resource was supported
+	supportedFrom := func(from string) func(tc *config.TypeConfiguration) error {
+		return func(tc *config.TypeConfiguration) error {
+			tc.SetSupportedFrom(from)
+			return nil
+		}
+	}
+
+	cfg := config.NewConfiguration()
+	cfg.SamplesURL = "https://github.com/Azure/azure-service-operator/tree/main/v2/config/samples"
+
+	omc := cfg.ObjectModelConfiguration
+	g.Expect(omc.ModifyType(person2020.Name(), supportedFrom("beta.0"))).To(Succeed())
+	g.Expect(omc.ModifyType(address2020.Name(), supportedFrom("beta.0"))).To(Succeed())
+	g.Expect(omc.ModifyType(person2021.Name(), supportedFrom("beta.2"))).To(Succeed())
+	g.Expect(omc.ModifyType(address2021.Name(), supportedFrom("beta.2"))).To(Succeed())
+
+	srr := cfg.SupportedResourcesReport
+	srr.Introduction = "These are the resources with Azure Service Operator support."
 
 	report := NewResourceVersionsReport(defs, cfg)
 
 	var buffer strings.Builder
 	g.Expect(report.WriteToBuffer(
-		&buffer, "https://github.com/Azure/azure-service-operator/tree/main/v2/config/samples")).
+		&buffer)).
 		To(Succeed())
 
 	gold.Assert(t, t.Name(), []byte(buffer.String()))

v2/tools/generator/internal/codegen/pipeline/testdata/TestGolden_ReportResourceVersions.golden

@@ -2,7 +2,7 @@
 title: Supported Resources
 ---
 
-These are the resources with Azure Service Operator support committed to our **main** branch, grouped by the originating ARM service. (Newly supported resources will appear in this list prior to inclusion in any ASO release.)
+These are the resources with Azure Service Operator support.
 
 ## Person
 

v2/tools/generator/internal/config/configuration.go

@@ -55,7 +55,8 @@ type Configuration struct {
 	SamplesURL string `yaml:"samplesUrl"`
 	// EmitDocFiles is used as a signal to create doc.go files for packages. If omitted, default is false.
 	EmitDocFiles bool `yaml:"emitDocFiles"`
-
+	// Destination file and additional information for our supported resources report
+	SupportedResourcesReport *SupportedResourcesReport `yaml:"supportedResourcesReport"`
 	// Additional information about our object model
 	ObjectModelConfiguration *ObjectModelConfiguration `yaml:"objectModelConfiguration"`
 
@@ -127,9 +128,13 @@ func (config *Configuration) GetPropertyTransformersError() error {
 
 // NewConfiguration returns a new empty Configuration
 func NewConfiguration() *Configuration {
-	return &Configuration{
+	result := &Configuration{
 		ObjectModelConfiguration: NewObjectModelConfiguration(),
 	}
+
+	result.SupportedResourcesReport = NewSupportedResourcesReport(result)
+
+	return result
 }
 
 // LoadConfiguration loads a `Configuration` from the specified file

v2/tools/generator/internal/config/supported_resources_report.go

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+package config
+
+import (
+	"path/filepath"
+)
+
+// SupportedResourcesReport is configuration for the report that lists all the supported resources.
+type SupportedResourcesReport struct {
+	cfg *Configuration // Back reference to global configuration
+
+	OutputPath   string `yaml:"outputPath,omitempty"`   // Destination filepath for the report, relative to DestinationGoModuleFile
+	Introduction string `yaml:"introduction,omitempty"` // Introduction to the report
+}
+
+// NewSupportedResourcesReport creates a new SupportedResourcesReport.
+func NewSupportedResourcesReport(cfg *Configuration) *SupportedResourcesReport {
+	return &SupportedResourcesReport{
+		cfg: cfg,
+	}
+}
+
+// FullOutputPath returns the fully qualified path to the output file.
+func (srr *SupportedResourcesReport) FullOutputPath() string {
+	return filepath.Join(
+		filepath.Dir(srr.cfg.DestinationGoModuleFile),
+		srr.OutputPath)
+}