render-adoc.go

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"sort"
	"strings"
	"text/template"

	"github.com/PuerkitoBio/goquery"
)

// render-adoc.go extracts information from groovydoc HTML pages, and renders
// the content into Antora templates. This process ensures that the final
// documentation reflects the source code accurately, without manual effort.
//
// Before running "go run render-adoc.go", ensure to run "./gradlew groovydoc".
// This should place HTML documents into "build/docs/groovydoc". From the pages
// describing the "Options" classes, the property information (name, type,
// description) is extracted, and then rendered into the Antora partials.
//
// render-adoc.go will process all templates (ending in .adoc.tmpl)
// automatically and assumes a corresponding "Options" class exists.
//
// This code is written in Go because it is extremly easy to write in Go.
// Also, most of ODS already requires Go so it is likely to be installed.
// On the flip side, it would be nice to have this in Groovy so that the
// shared library does not require another language to be built ... maybe an
// optimization for later?

const (
	pathSep                    = string(os.PathSeparator)
	globalComponentStagePrefix = "odsComponentStage"
	adocTemplateSuffix         = ".adoc.tmpl"
)

var (
	groovydocComponentPath = filepath.FromSlash("build/docs/groovydoc/org/ods/component")
	antoraPartialsPath     = filepath.FromSlash("docs/modules/jenkins-shared-library/partials")
)

func main() {
	adocTemplatePrefix := fmt.Sprintf(filepath.FromSlash("%s/%s"), antoraPartialsPath, globalComponentStagePrefix)
	templateFiles, err := filepath.Glob(fmt.Sprintf(filepath.FromSlash("%s/*%s"), antoraPartialsPath, adocTemplateSuffix))
	check(err)
	for _, templateFile := range templateFiles {
		stageName := strings.TrimPrefix(templateFile, adocTemplatePrefix)
		stageName = strings.TrimSuffix(stageName, adocTemplateSuffix)
		renderDocs(stageName)
	}
}

func check(e error) {
	if e != nil {
		panic(e)
	}
}

type option struct {
	Name        string
	Type        string
	Description string
}

type docData struct {
	Options []option
}

func extractType(rawType string) string {
	cleanedType := strings.Replace(strings.TrimSpace(rawType), " ", " ", -1)
	cleanedType = strings.Replace(cleanedType, "java.util.", "", -1)
	cleanedType = strings.Replace(cleanedType, "java.lang.", "", -1)
	return cleanedType
}

func getOptions(filename string) []option {
	optionsDocFile, err := os.Open(filename)
	check(err)
	optionsDoc, err := goquery.NewDocumentFromReader(optionsDocFile)
	check(err)
	options := []option{}
	optionsDoc.Find("div.details ul.blockListLast").Each(func(i int, s *goquery.Selection) {
		optionType := extractType(s.Find("li.blockList h4").Nodes[0].FirstChild.Data)
		optionName := strings.TrimSpace(s.Find("li.blockList h4 strong").Text())
		optionDesc := strings.TrimSpace(s.Find("p").Text())
		options = append(options, option{Name: optionName, Type: optionType, Description: optionDesc})
	})
	return options
}

func renderTemplate(targetFilename string, data docData) {
	targetFile, err := os.Create(targetFilename)
	check(err)
	templateFilename := targetFilename + ".tmpl"
	templateFileParts := strings.Split(templateFilename, "/")
	templateDisplayname := templateFileParts[len(templateFileParts)-1]
	_, err = targetFile.WriteString(
		"// Document generated by render-adoc.go from " + templateDisplayname + "; DO NOT EDIT.\n\n",
	)
	check(err)
	tmpl, err := template.ParseFiles(templateFilename)
	check(err)
	err = tmpl.Execute(targetFile, data)
	check(err)
}

func mergeAndSortOptions(stageOptions, globalOptions []option) []option {
	for _, globalOption := range globalOptions {
		globalOptionOverriden := false
		for _, stageOption := range stageOptions {
			if globalOption.Name == stageOption.Name {
				globalOptionOverriden = true
			}
		}
		if !globalOptionOverriden {
			stageOptions = append(stageOptions, globalOption)
		}
	}
	sort.SliceStable(stageOptions, func(i, j int) bool {
		return stageOptions[i].Name < stageOptions[j].Name
	})
	return stageOptions
}

// renderDocs looks for HTML documents of the general options and the
// stage-specific options, extracts the information into a struct, and
// executes the Asciidoctor template belonging to the given stage.
func renderDocs(stageName string) {
	stageOptions := getOptions(fmt.Sprintf("%s/%sOptions.html", groovydocComponentPath, stageName))
	globalOptions := getOptions(fmt.Sprintf("%s/Options.html", groovydocComponentPath))
	stageOptions = mergeAndSortOptions(stageOptions, globalOptions)
	data := docData{Options: stageOptions}
	renderTemplate(
		fmt.Sprintf("%s/%s%s.adoc", antoraPartialsPath, globalComponentStagePrefix, stageName),
		data,
	)
}