wip

docs/docs_updated_test.go

@@ -20,28 +20,7 @@ var fixTestsFlag = flag.Bool("fix-tests", false, "update the test files with the
 func TestCompatibleComponentsSectionsUpdated(t *testing.T) {
 	for _, name := range component.AllNames() {
 		t.Run(name, func(t *testing.T) {
-			generated, err := generator.GenerateCompatibleComponentsSection(name)
-			require.NoError(t, err, "failed to generate references section for %q", name)
-
-			if generated == "" {
-				t.Skipf("no compatible components section defined for %q", name)
-			}
-
-			if *fixTestsFlag {
-				err = generator.WriteCompatibleComponentsSection(name)
-				require.NoError(t, err, "failed to write generated references section for %q", name)
-				t.Log("updated the docs with generated content")
-			}
-
-			actual, err := generator.ReadCompatibleComponentsSection(name)
-			require.NoError(t, err, "failed to read generated components section for %q, try running 'go generate ./docs'", name)
-			require.Contains(
-				t,
-				actual,
-				strings.TrimSpace(generated),
-				"expected documentation for %q to contain generated references section, try running 'go generate ./docs'",
-				name,
-			)
+			runForGenerator(t, generator.NewLinksToTypesGenerator(name))
 		})
 	}
 }

docs/generator/component_links.go

@@ -1,68 +1,24 @@
 package generator
 
 import (
-	"bytes"
 	"fmt"
 	"github.com/grafana/agent/component/metadata"
-	"os"
 )
 
-const (
-	startDelimiter = "<!-- START GENERATED COMPATIBLE COMPONENTS -->"
-	endDelimiter   = "<!-- END GENERATED COMPATIBLE COMPONENTS -->"
-)
-
-func WriteCompatibleComponentsSection(componentName string) error {
-	filePath := pathToComponentMarkdown(componentName)
-	newSection, err := GenerateCompatibleComponentsSection(componentName)
-	if err != nil {
-		return err
-	}
-	fileContents, err := os.ReadFile(filePath)
-	if err != nil {
-		return err
-	}
-
-	startMarker := startMarkerBytes()
-	endMarker := endMarkerBytes()
-	replacement := append(append(startMarker, []byte(newSection)...), endMarker...)
-
-	startIndex := bytes.Index(fileContents, startMarker)
-	endIndex := bytes.Index(fileContents, endMarker)
-	var newFileContents []byte
-	if startIndex == -1 || endIndex == -1 {
-		// Append the new section to the end of the file
-		newFileContents = append(fileContents, append([]byte("\n"), replacement...)...)
-	} else {
-		// Replace the section with the new content
-		newFileContents = append(fileContents[:startIndex], replacement...)
-		newFileContents = append(newFileContents, fileContents[endIndex+len(endMarker):]...)
-	}
-
-	err = os.WriteFile(filePath, newFileContents, 0644)
-	return err
+type LinksToTypesGenerator struct {
+	component string
 }
 
-func ReadCompatibleComponentsSection(componentName string) (string, error) {
-	filePath := pathToComponentMarkdown(componentName)
-	fileContents, err := os.ReadFile(filePath)
-	if err != nil {
-		return "", err
-	}
-
-	startMarker := startMarkerBytes()
-	endMarker := endMarkerBytes()
-	startIndex := bytes.Index(fileContents, startMarker)
-	endIndex := bytes.Index(fileContents, endMarker)
-	if startIndex == -1 || endIndex == -1 {
-		return "", fmt.Errorf("compatible components section not found in %q", filePath)
-	}
+func NewLinksToTypesGenerator(component string) *LinksToTypesGenerator {
+	return &LinksToTypesGenerator{component: component}
+}
 
-	return string(fileContents[startIndex+len(startMarker) : endIndex]), nil
+func (l *LinksToTypesGenerator) Name() string {
+	return fmt.Sprintf("generator of links to types for %q reference page", l.component)
 }
 
-func GenerateCompatibleComponentsSection(componentName string) (string, error) {
-	meta, err := metadata.ForComponent(componentName)
+func (l *LinksToTypesGenerator) Generate() (string, error) {
+	meta, err := metadata.ForComponent(l.component)
 	if err != nil {
 		return "", err
 	}
@@ -71,8 +27,8 @@ func GenerateCompatibleComponentsSection(componentName string) (string, error) {
 	}
 
 	heading := "\n## Compatible components\n\n"
-	acceptingSection := acceptingComponentsSection(componentName, meta)
-	outputSection := outputComponentsSection(componentName, meta)
+	acceptingSection := acceptingComponentsSection(l.component, meta)
+	outputSection := outputComponentsSection(l.component, meta)
 
 	if acceptingSection == "" && outputSection == "" {
 		return "", nil
@@ -85,6 +41,35 @@ func GenerateCompatibleComponentsSection(componentName string) (string, error) {
 	return heading + acceptingSection + outputSection + note, nil
 }
 
+func (l *LinksToTypesGenerator) Read() (string, error) {
+	content, err := readBetweenMarkers(l.startMarker(), l.endMarker(), l.pathToComponentMarkdown())
+	if err != nil {
+		return "", fmt.Errorf("failed to read existing content for %q: %w", l.Name(), err)
+	}
+	return content, err
+}
+
+func (l *LinksToTypesGenerator) Write() error {
+	newSection, err := l.Generate()
+	if err != nil {
+		return err
+	}
+	newSection = "\n" + newSection + "\n"
+	return writeBetweenMarkers(l.startMarker(), l.endMarker(), l.pathToComponentMarkdown(), newSection, true)
+}
+
+func (l *LinksToTypesGenerator) startMarker() string {
+	return "<!-- START GENERATED COMPATIBLE COMPONENTS -->"
+}
+
+func (l *LinksToTypesGenerator) endMarker() string {
+	return "<!-- END GENERATED COMPATIBLE COMPONENTS -->"
+}
+
+func (l *LinksToTypesGenerator) pathToComponentMarkdown() string {
+	return fmt.Sprintf("sources/flow/reference/components/%s.md", l.component)
+}
+
 func outputComponentsSection(name string, meta metadata.Metadata) string {
 	section := ""
 	for _, outputDataType := range meta.Exports {
@@ -110,15 +95,3 @@ func acceptingComponentsSection(componentName string, meta metadata.Metadata) st
 	}
 	return section
 }
-
-func pathToComponentMarkdown(name string) string {
-	return fmt.Sprintf("sources/flow/reference/components/%s.md", name)
-}
-
-func endMarkerBytes() []byte {
-	return []byte(endDelimiter + "\n")
-}
-
-func startMarkerBytes() []byte {
-	return []byte(startDelimiter + "\n")
-}