🧹 make lr docs yaml file loading for markdown generation more robust (#…

…3845)

* Make the yaml file for docs generation required

The way the filestat was being checked if a user gave an incorrect path
we'd love that the file was not provided and move on. These should
always be provided so let's just not include this check entirely.

I also improved a bit of text while I was in here and fixed incorrect
help

Signed-off-by: Tim Smith <[email protected]>

* Add the actual description into the pack readme as well

Signed-off-by: Tim Smith <[email protected]>

* 🧹 only load the yaml metadata if a file was provided

---------

Signed-off-by: Tim Smith <[email protected]>
Co-authored-by: Christoph Hartmann <[email protected]>

providers-sdk/v1/lr/cli/cmd/markdown.go

@@ -26,8 +26,8 @@ import (
 func init() {
 	markdownCmd.Flags().String("pack-name", "", "name of the resource pack")
 	markdownCmd.Flags().String("description", "", "description of the resource pack")
-	markdownCmd.Flags().String("docs-file", "", "optional docs yaml to enrich the resource information")
-	markdownCmd.Flags().StringP("output", "o", ".build", "optional docs yaml to enrich the resource information")
+	markdownCmd.Flags().String("docs-file", "", "docs yaml to enrich the resource information")
+	markdownCmd.Flags().StringP("output", "o", ".build", "local path to the resource pack in the docs repo")
 	rootCmd.AddCommand(markdownCmd)
 }
 
@@ -69,9 +69,9 @@ var markdownCmd = &cobra.Command{
 		}
 
 		var lrDocsData docs.LrDocs
+
 		docsFilepath, _ := cmd.Flags().GetString("docs-file")
-		_, err = os.Stat(docsFilepath)
-		if err == nil {
+		if docsFilepath != "" { // as soon as a path has been provided, we try to load the file
 			content, err := os.ReadFile(docsFilepath)
 			if err != nil {
 				log.Fatal().Err(err).Msg("could not read file " + docsFilepath)
@@ -80,10 +80,7 @@ var markdownCmd = &cobra.Command{
 			if err != nil {
 				log.Fatal().Err(err).Msg("could not load yaml data")
 			}
-
 			log.Info().Int("resources", len(lrDocsData.Resources)).Msg("loaded docs from " + docsFilepath)
-		} else {
-			log.Info().Msg("no docs file provided")
 		}
 
 		// to ensure we generate the same markdown, we sort the resources first
@@ -175,7 +172,8 @@ func (l *lrSchemaRenderer) renderToc(packName string, description string, resour
 
 	// render content
 	builder.WriteString("# Mondoo " + packName + " Resource Pack Reference\n\n")
-	builder.WriteString("In this pack:\n\n")
+	builder.WriteString(description + "\n\n")
+	builder.WriteString("Resources included in this pack:\n\n")
 	rows := [][]string{}
 
 	for i := range resources {