From 349c3ef74b96099581568fa5ead013d43b586cbd Mon Sep 17 00:00:00 2001
From: Adrien Delorme <adrien.delorme@icloud.com>
Date: Wed, 12 Jun 2019 16:25:08 +0200
Subject: [PATCH] cmd/struct-markdown: also generate docs from header comments
 of a struct

& generate it for ISOConfig
---
 cmd/struct-markdown/main.go                   | 10 +++-
 cmd/struct-markdown/template.go               |  2 +
 .../source/partials/common/_ISOConfig.html.md | 52 +++++++++++++++++++
 3 files changed, 62 insertions(+), 2 deletions(-)
 create mode 100644 website/source/partials/common/_ISOConfig.html.md

diff --git a/cmd/struct-markdown/main.go b/cmd/struct-markdown/main.go
index e5a31ff5d..545ed576f 100644
--- a/cmd/struct-markdown/main.go
+++ b/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)
diff --git a/cmd/struct-markdown/template.go b/cmd/struct-markdown/template.go
index e4a3e1a87..1a6c3bdc9 100644
--- a/cmd/struct-markdown/template.go
+++ b/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 -}}`))
diff --git a/website/source/partials/common/_ISOConfig.html.md b/website/source/partials/common/_ISOConfig.html.md
new file mode 100644
index 000000000..ab0097107
--- /dev/null
+++ b/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"
+}
+```