hcl2 docs pass (#9375)

* moved blocks and functions top the nav list for easier access ( I think those will be used a lot)
* added a concrete fileset example
* added more concrete examples in the blocks doc

website/data/docs-navigation.js

@@ -9,11 +9,6 @@ export default [
   {
     category: 'from-1.5',
     content: [
-      'variables',
-      'locals',
-      'syntax',
-      'expressions',
-      'syntax-json',
       {
         category: 'blocks',
         content: [ 
@@ -143,6 +138,11 @@ export default [
           },
         ],
       },
+      'variables',
+      'locals',
+      'syntax',
+      'expressions',
+      'syntax-json',
     ],
   },
   '--------',

website/pages/docs/from-1.5/blocks/build/index.mdx

@@ -27,6 +27,71 @@ Define [top-level `source` blocks](/docs/from-1.5/blocks/source) to configure
 your builders. The list of available builders can be found in the
 [builders](/docs/builders) section.
 
+## Naming your builds
+
+The optional `name` field of the `build` block can be used to set the name of a
+build. Named builds will prefix the log lines in a `packer build` with the name
+of the build block. For example:
+
+```hcl
+source "null" "first-example" {
+    communicator = "none"
+}
+
+source "null" "second-example" {
+    communicator = "none"
+}
+
+build {
+    name = "a"
+
+    sources = [
+        "sources.null.first-example",
+        "sources.null.second-example",
+    ]
+}
+
+
+build {
+    sources = ["sources.null.second-example"]
+}
+```
+
+Will output:
+
+```shell-session
+> packer build ./folder
+Build 'a.null.first-example' finished.
+Build 'a.null.second-example' finished.
+Build 'null.second-example' finished.
+
+==> Builds finished. The artifacts of successful builds are:
+--> a.null.first-example: Did not export anything. This is the null builder
+--> a.null.second-example: Did not export anything. This is the null builder
+--> null.second-example: Did not export anything. This is the null builder
+```
+
+### Running only specific builds
+
+The `-only`/`-except` flags will match a source's `type.name` and run 'only'
+matching **builders** (source) or all referenced builders 'except' the matching
+ones, for example with the same config file:
+
+```shell-session
+> packer build -only "*.second" ./folder
+Build 'null.second-example' finished.
+Build 'a.null.second-example' finished.
+
+==> Builds finished. The artifacts of successful builds are:
+--> a.null.second-example: Did not export anything. This is the null builder
+--> null.second-example: Did not export anything. This is the null builder
+```
+
+Here `'a.null.first-example'` was skipped.
+
+-> Note: It is not yet possible to match a named `build` block to do this, but
+this is soon going to be possible. So here "a.*" will match nothing.
+
 
 ## Related
 

website/pages/docs/from-1.5/blocks/build/provisioner.mdx

@@ -43,14 +43,34 @@ effectively the same:
 
 ```hcl
 # builds.pkr.hcl
+
+source "amazon-ebs" "first-example" {
+  #...
+}
+
+source "amazon-ebs" "second-example" {
+  #...
+}
+
 build {
-  # ...
+  source = [
+    "source.amazon-ebs.first-example",
+    "source.amazon-ebs.second-example",
+  ]
   provisioner "shell" {
-      inline = [
-        "echo provisioning all the things",
-        "echo the value of 'foo' is '${var.foo}'",
+    # This provisioner only runs for the 'first-example' source.
+    only = ["source.amazon-ebs.first-example"] 
+
+    inline = [
+      "echo provisioning all the things",
+      "echo the value of 'foo' is '${var.foo}'",
+    ]
+  }
+  provisioner "shell" {
+    # This runs with all sources.
+    inline = [
+        "echo Hi World!"
       ]
-      only = ["source.amazon-ebs.example"]
   }
 }
 ```

website/pages/docs/from-1.5/blocks/build/source.mdx

@@ -16,14 +16,34 @@ source and to set specific fields.
 
 ```hcl
 # builds.pkr.hcl
+source "lxd" "arch" {
+  image = "archlinux"
+}
+
 build {
-  source "amazon-ebs.example" {
-    output = "specific-value"
+  source "lxd.arch" {
+     output_image = "nomad"
+  }
+
+  provisioner "shell" {
+    inline = [ "echo installing nomad" ]
+  }
+}
+
+build {
+  source "lxd.arch" {
+     output_image = "consul"
+  }
+
+  provisioner "shell" {
+    inline = [ "echo installing consul" ]
   }
-  #  ...
 }
 ```
 
+This allows to have commonly defined source settings with specific parts of it
+defined inside the specific build block.
+
 -> **Note:** It is **not allowed** to set the same field in a top-level source
   block and in a used source block. For example, if in the above example, the
   top-level "amazon-ebs.example" source block also had an `output` field;

website/pages/docs/from-1.5/blocks/index.mdx

@@ -24,8 +24,16 @@ list of all of the available built-in HCL2 blocks.
 
 `@include 'from-1.5/variables/foo-block.mdx'`
 
+* [Variable block documentation](/docs/from-1.5/blocks/variable).
+
 `@include 'from-1.5/locals/example-block.mdx'`
 
+* [Locals block documentation](/docs/from-1.5/blocks/locals).
+
 `@include 'from-1.5/sources/example-block.mdx'`
 
+* [source block documentation](/docs/from-1.5/blocks/source).
+
 `@include 'from-1.5/builds/example-block.mdx'`
+
+* [build block documentation](/docs/from-1.5/blocks/build).

website/pages/docs/from-1.5/functions/file/fileset.mdx

@@ -37,39 +37,67 @@ before Packer takes any actions.
 ## Examples
 
 ```shell-session
-> fileset(path.folder, "files/*.txt")
+> tree pkr-consul  
+pkr-consul
+├── build-linux.pkr.hcl
+└── linux
+    ├── files
+    │   ├── hello.txt
+    │   └── world.txt
+    └── scripts
+        ├── script-1-install.sh
+        └── script-2-setup.sh
+
+3 directories, 5 files
+
+> fileset(".", "*") | packer console pkr-consul
 [
-  "files/hello.txt",
-  "files/world.txt",
+  "build-linux.pkr.hcl",
+]
+
+> echo 'fileset(".", "linux/scripts/*")' | packer console pkr-consul
+[
+  "linux/scripts/script-1-install.sh",
+  "linux/scripts/script-2-setup.sh",
 ]
 
-> fileset(path.folder, "files/{hello,world}.txt")
+> echo 'fileset("linux", "files/{hello,world}.txt")' | packer console pkr-consul
 [
   "files/hello.txt",
   "files/world.txt",
 ]
 
-> fileset("${path.folder}/files", "*")
+> echo 'fileset("./linux/files", "*")' | packer console pkr-consul
 [
   "hello.txt",
   "world.txt",
 ]
 
-> fileset("${path.folder}/files", "**")
+> echo 'fileset("./linux", "**")' | packer console pkr-consul
 [
-  "hello.txt",
-  "world.txt",
-  "subdirectory/anotherfile.txt",
+  "files/hello.txt",
+  "files/world.txt",
+  "scripts/script-1-install.sh",
+  "scripts/script-2-setup.sh",
 ]
 ```
 
-A common use of `fileset` is to create one resource instance per matched file, using
-[the `for_each` meta-argument](https://www.terraform.io/docs/configuration/resources.html#for_each-multiple-resource-instances-defined-by-a-map-or-set-of-strings):
+A common use of `fileset` is to set the `scripts` field of a `shell`
+provisioner with a list of matching scripts to run.
 
 ```hcl
-resource "example_thing" "example" {
-  for_each = fileset(path.folder, "files/*")
-
-  # other configuration using each.value
-}
+build {
+  sources = [
+    "source.amazon-ebs.linux",
+  ]
+
+  provisioner "shell" {
+    scripts = fileset(".", "linux/scripts/*")
+  }
 ```
+
+List of provisioners with a `scripts` field:
+* [`shell`](/docs/provisioners/shell)
+* [`powershell`](/docs/provisioners/powershell)
+* [`shell-local`](/docs/provisioners/shell-local)
+* [`windows-shell`](/docs/provisioners/windows-shell)

website/pages/docs/from-1.5/index.mdx

@@ -25,8 +25,8 @@ language features exist only to make the definition of builds more flexible and
 convenient.
 
 `packer build` takes one argument. When a directory is passed, all files in the
-folder with a name ending with ".pkr.hcl" or ".pkr.json" will be parsed using
-the HCL2 format. When a file ending with ".pkr.hcl" or ".pkr.json" is passed it
+folder with a name ending with `.pkr.hcl` or `.pkr.json` will be parsed using
+the HCL2 format. When a file ending with `.pkr.hcl` or `.pkr.json` is passed it
 will be parsed using the HCL2 schema. For every other case; the _JSON only_ old
 packer schema will be used.
 

website/pages/partials/from-1.5/builds/example-block.mdx

@@ -20,8 +20,8 @@ build {
         name = var.foo
     }
 
-    provisioner "shell-local" {
-        inline = ["echo Hello World"]
+    provisioner "shell" {
+        scripts = fileset(".", "scripts/{install,secure}.sh")
     }
 
     post-processor "shell-local" {