// Copyright 2017 Google Inc. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package main import ( "android/soong/android" "bytes" "html/template" "io/ioutil" "path/filepath" "sort" "github.com/google/blueprint/bootstrap" "github.com/google/blueprint/bootstrap/bpdoc" ) type perPackageTemplateData struct { Name string Modules []moduleTypeTemplateData } type moduleTypeTemplateData struct { Name string Synopsis template.HTML Properties []bpdoc.Property } // The properties in this map are displayed first, according to their rank. // TODO(jungjw): consider providing module type-dependent ranking var propertyRank = map[string]int{ "name": 0, "src": 1, "srcs": 2, "exclude_srcs": 3, "defaults": 4, "host_supported": 5, "device_supported": 6, } // For each module type, extract its documentation and convert it to the template data. func moduleTypeDocsToTemplates(moduleTypeList []*bpdoc.ModuleType) []moduleTypeTemplateData { result := make([]moduleTypeTemplateData, 0) // Combine properties from all PropertyStruct's and reorder them -- first the ones // with rank, then the rest of the properties in alphabetic order. for _, m := range moduleTypeList { item := moduleTypeTemplateData{ Name: m.Name, Synopsis: m.Text, Properties: make([]bpdoc.Property, 0), } props := make([]bpdoc.Property, 0) for _, propStruct := range m.PropertyStructs { props = append(props, propStruct.Properties...) } sort.Slice(props, func(i, j int) bool { if rankI, ok := propertyRank[props[i].Name]; ok { if rankJ, ok := propertyRank[props[j].Name]; ok { return rankI < rankJ } else { return true } } if _, ok := propertyRank[props[j].Name]; ok { return false } return props[i].Name < props[j].Name }) // Eliminate top-level duplicates. TODO(jungjw): improve bpdoc to handle this. previousPropertyName := "" for _, prop := range props { if prop.Name == previousPropertyName { oldProp := &item.Properties[len(item.Properties)-1].Properties bpdoc.CollapseDuplicateProperties(oldProp, &prop.Properties) } else { item.Properties = append(item.Properties, prop) } previousPropertyName = prop.Name } result = append(result, item) } sort.Slice(result, func(i, j int) bool { return result[i].Name < result[j].Name }) return result } func getPackages(ctx *android.Context, config interface{}) ([]*bpdoc.Package, error) { moduleTypeFactories := android.ModuleTypeFactoriesForDocs() return bootstrap.ModuleTypeDocs(ctx.Context, config, moduleTypeFactories) } func writeDocs(ctx *android.Context, config interface{}, filename string) error { packages, err := getPackages(ctx, config) if err != nil { return err } // Produce the top-level, package list page first. tmpl := template.Must(template.Must(template.New("file").Parse(packageListTemplate)).Parse(copyBaseUrl)) buf := &bytes.Buffer{} err = tmpl.Execute(buf, packages) if err == nil { err = ioutil.WriteFile(filename, buf.Bytes(), 0666) } // Now, produce per-package module lists with detailed information, and a list // of keywords. keywordsTmpl := template.Must(template.New("file").Parse(keywordsTemplate)) keywordsBuf := &bytes.Buffer{} for _, pkg := range packages { // We need a module name getter/setter function because I couldn't // find a way to keep it in a variable defined within the template. currentModuleName := "" tmpl := template.Must( template.Must(template.New("file").Funcs(map[string]interface{}{ "setModule": func(moduleName string) string { currentModuleName = moduleName return "" }, "getModule": func() string { return currentModuleName }, }).Parse(perPackageTemplate)).Parse(copyBaseUrl)) buf := &bytes.Buffer{} modules := moduleTypeDocsToTemplates(pkg.ModuleTypes) data := perPackageTemplateData{Name: pkg.Name, Modules: modules} err = tmpl.Execute(buf, data) if err != nil { return err } pkgFileName := filepath.Join(filepath.Dir(filename), pkg.Name+".html") err = ioutil.WriteFile(pkgFileName, buf.Bytes(), 0666) if err != nil { return err } err = keywordsTmpl.Execute(keywordsBuf, data) if err != nil { return err } } // Write out list of keywords. This includes all module and property names, which is useful for // building syntax highlighters. keywordsFilename := filepath.Join(filepath.Dir(filename), "keywords.txt") err = ioutil.WriteFile(keywordsFilename, keywordsBuf.Bytes(), 0666) return err } // TODO(jungjw): Consider ordering by name. const ( packageListTemplate = ` Build Docs {{template "copyBaseUrl"}}

Soong Modules Reference

The latest versions of Android use the Soong build system, which greatly simplifies build configuration over the previous Make-based system. This site contains the generated reference files for the Soong build system. {{range $pkg := .}} {{end}}
Package Module types
{{.Path}} {{range $i, $mod := .ModuleTypes}}{{if $i}}, {{end}}{{$mod.Name}}{{end}}
` perPackageTemplate = ` Build Docs {{template "copyBaseUrl"}} {{- /* Fixed sidebar with module types */ -}} {{/* Main panel with H1 section per module type */}}
{{range $moduleType := .Modules}} {{setModule $moduleType.Name}}

{{$moduleType.Name}}

{{if $moduleType.Synopsis }}{{$moduleType.Synopsis}}{{else}}Missing synopsis{{end}} {{- /* Comma-separated list of module attributes' links module attributes */ -}}
{{range $i,$prop := $moduleType.Properties }} {{ if gt $i 0 }}, {{end -}} {{$prop.Name}} {{- end -}}
{{- /* Property description */ -}} {{- template "properties" $moduleType.Properties -}} {{- end -}} {{define "properties" -}} {{range .}} {{if .Properties -}}
⊕{{.Name}} {{- range .OtherNames -}}, {{.}}{{- end -}}
{{- .Text}} {{range .OtherTexts}}{{.}}{{end}} {{template "properties" .Properties -}}
{{- else -}}
 {{.Name}} {{range .OtherNames}}, {{.}}{{end -}} {{.Type}} {{- if .Text -}}{{if ne .Text "\n"}}, {{end}}{{.Text}}{{- end -}} {{- with .OtherTexts -}}{{.}}{{- end -}} {{- if .Default -}}Default: {{.Default}}{{- end -}}
{{- end}} {{- end -}} {{- end -}}
` copyBaseUrl = ` {{define "copyBaseUrl"}} {{end}} ` keywordsTemplate = ` {{range $moduleType := .Modules}}{{$moduleType.Name}}:{{range $property := $moduleType.Properties}}{{$property.Name}},{{end}} {{end}} ` )