Add validation script for docs generation (#11411)

* Add validation script for docs generation

* Apply suggestions from code review

Co-authored-by: Victor Martinez <[email protected]>

* Move check to makefile

* Update .github/workflows/validate-docs-structure.yml

Co-authored-by: Victor Martinez <[email protected]>

* Use magefile

* Add make mage

* Remove makefile target

* Remove trailing space

* Add target dependency

---------

Co-authored-by: Victor Martinez <[email protected]>
Co-authored-by: Shaunak Kashyap <[email protected]>

Author: 3 people

.github/workflows/validate-docs-structure.yml

@@ -0,0 +1,28 @@
+name: Validate docs generation structure
+
+on:
+  pull_request:
+    paths:
+      - 'internal/edot/**'
+      - 'internal/pkg/otel/**'
+      - '.github/workflows/validate-docs-structure.yml'
+
+jobs:
+  validate-structure:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: 'go.mod'
+      
+      - name: Install mage
+        uses: magefile/mage-action@6f50bbb8ea47d56e62dee92392788acbc8192d0b # v3.1.0
+        with:
+          install-only: true
+      
+      - name: Validate expected files for docs generation
+        run: mage check:docsFiles
+

magefile.go

@@ -450,9 +450,9 @@ func (Build) TestBinaries() error {
 	return nil
 }
 
-// All run all the code checks.
+// All run all the code and docs checks.
 func (Check) All() {
-	mg.SerialDeps(Check.License, Integration.Check)
+	mg.SerialDeps(Check.License, Integration.Check, Check.DocsFiles)
 }
 
 // License makes sure that all the Golang files have the appropriate license header.
@@ -462,6 +462,40 @@ func (Check) License() error {
 	return sh.RunV("go-licenser", "-d", "-license", "Elasticv2")
 }
 
+// DocsFiles validates that files required by the docs generation script exist.
+func (Check) DocsFiles() error {
+	fmt.Println("Validating files required by docs/scripts/update-docs/update-components-docs.py")
+
+	requiredFiles := []string{
+		"go.mod",
+		"internal/pkg/otel/components.yml",
+		"internal/pkg/otel/samples/linux/gateway.yml",
+	}
+
+	missing := false
+	for _, file := range requiredFiles {
+		if _, err := os.Stat(file); os.IsNotExist(err) {
+			fmt.Printf("❌ Missing: %s\n", file)
+			missing = true
+		} else {
+			fmt.Printf("✅ Found: %s\n", file)
+		}
+	}
+
+	if missing {
+		fmt.Println()
+		return fmt.Errorf("one or more files required by the docs generation script are missing.\n" +
+			"If these files were intentionally moved, please update:\n" +
+			"  - docs/scripts/update-docs/update-components-docs.py\n" +
+			"  - magefile.go (Check.DocsFiles function)\n" +
+			"  - .github/workflows/validate-docs-structure.yml")
+	}
+
+	fmt.Println()
+	fmt.Println("✅ All required files are present.")
+	return nil
+}
+
 // Changes run git status --porcelain and return an error if we have changes or uncommitted files.
 func (Check) Changes() error {
 	out, err := sh.Output("git", "status", "--porcelain")