cmd/struct-markdown: also generate docs from header comments of a struct

& generate it for ISOConfig

cmd/struct-markdown/main.go

@@ -60,6 +60,12 @@ func main() {
 		}
 
 		fields := structDecl.Fields.List
+		header := Struct{
+			SourcePath: paths[1],
+			Name:       typeSpec.Name.Name,
+			Filename:   "_" + typeSpec.Name.Name + ".html.md",
+			Header:     typeDecl.Doc.Text(),
+		}
 		required := Struct{
 			SourcePath: paths[1],
 			Name:       typeSpec.Name.Name,
@@ -115,8 +121,8 @@ func main() {
 		dir := filepath.Join(packerDir, "website", "source", "partials", builderName)
 		os.MkdirAll(dir, 0755)
 
-		for _, str := range []Struct{required, notRequired} {
-			if len(str.Fields) == 0 {
+		for _, str := range []Struct{header, required, notRequired} {
+			if len(str.Fields) == 0 && len(str.Header) == 0 {
 				continue
 			}
 			outputPath := filepath.Join(dir, str.Filename)

cmd/struct-markdown/template.go

@@ -15,6 +15,7 @@ type Struct struct {
 	SourcePath string
 	Name       string
 	Filename   string
+	Header     string
 	Fields     []Field
 }
 
@@ -23,6 +24,7 @@ var structDocsTemplate = template.Must(template.New("structDocsTemplate").
 		"indent": indent,
 	}).
 	Parse(`<!-- Code generated from the comments of the {{ .Name }} struct in {{ .SourcePath }}; DO NOT EDIT MANUALLY -->
+{{ .Header -}}
 {{range .Fields}}
 -   ` + "`" + `{{ .Name}}` + "`" + ` ({{ .Type }}) - {{ .Docs | indent 4 }}
 {{- end -}}`))

website/source/partials/common/_ISOConfig.html.md

@@ -0,0 +1,52 @@
+<!-- Code generated from the comments of the ISOConfig struct in common/iso_config.go; DO NOT EDIT MANUALLY -->
+By default, Packer will symlink, download or copy image files to the Packer
+cache into a "`hash($iso_url+$iso_checksum).$iso_target_extension`" file.
+Packer uses [hashicorp/go-getter](https://github.com/hashicorp/go-getter) in
+file mode in order to perform a download.
+
+go-getter supports the following protocols:
+
+* Local files
+* Git
+* Mercurial
+* HTTP
+* Amazon S3
+
+\~&gt; On windows - when referencing a local iso - if packer is running
+without symlinking rights, the iso will be copied to the cache folder. Read
+[Symlinks in Windows 10
+!](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/)
+for more info.
+
+Examples:
+go-getter can guess the checksum type based on `iso_checksum` len.
+
+``` json
+{
+  "iso_checksum": "946a6077af6f5f95a51f82fdc44051c7aa19f9cfc5f737954845a6050543d7c2",
+  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
+}
+```
+
+``` json
+{
+  "iso_checksum_type": "file",
+  "iso_checksum": "ubuntu.org/..../ubuntu-14.04.1-server-amd64.iso.sum",
+  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
+}
+```
+
+``` json
+{
+  "iso_checksum_url": "./shasums.txt",
+  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
+}
+```
+
+``` json
+{
+  "iso_checksum_type": "sha256",
+  "iso_checksum_url": "./shasums.txt",
+  "iso_url": "ubuntu.org/.../ubuntu-14.04.1-server-amd64.iso"
+}
+```