[920] Properly document the devices syntax (#1172)

Thanks to @nazar-pc for the proper syntax
Closes #920

Move resource documentation into the documentation folder

Signed-off-by: Dan Webb <dan.webb@damacus.io>

documentation/docker_exec.md

@@ -0,0 +1,24 @@
+# docker_exec
+
+The `docker_exec` resource allows you to execute commands inside of a running container.
+
+## Actions
+
+- `:run` - Runs the command
+
+## Properties
+
+- `host` - Daemon socket(s) to connect to - `tcp://host:port`, `unix:///path/to/socket`, `fd://*` or `fd://socketfd`.
+- `command` - A command structured as an Array similar to `CMD` in a Dockerfile.
+- `container` - Name of the container to execute the command in.
+- `timeout`- Seconds to wait for an attached container to return. Defaults to 60 seconds.
+- `container_obj`
+
+## Examples
+
+```ruby
+docker_exec 'touch_it' do
+  container 'busybox_exec'
+  command ['touch', '/tmp/onefile']
+end
+```

documentation/docker_image.md

@@ -0,0 +1,186 @@
+# docker_image
+
+The `docker_image` is responsible for managing Docker image pulls, builds, and deletions. It speaks directly to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#tag/Image).
+
+## Actions
+
+- `:pull` - Pulls an image from the registry. Default action.
+- `:pull_if_missing` - Pulls an image from the registry, only if it missing
+- `:build` - Builds an image from a Dockerfile, directory, or tarball
+- `:build_if_missing` - Same build, but only if it is missing
+- `:save` - Exports an image to a tarball at `destination`
+- `:import` - Imports an image from a tarball at `destination`
+- `:remove` - Removes (untags) an image
+- `:push` - Pushes an image to the registry
+
+## Properties
+
+The `docker_image` resource properties mostly corresponds to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#tag/Image) as driven by the [docker-api Ruby gem](https://github.com/swipely/docker-api)
+
+A `docker_image`'s full identifier is a string in the form `<repo>:<tag>`. There is some nuance around naming using the
+public registry vs a private one.
+
+- `repo` - aka `image_name` - The first half of a Docker image's identity. This is a string in the form: `registry:port/owner/image_name`. If the `registry:port` portion is left off, Docker will implicitly use the Docker public registry. "Official Images" omit the owner part. This means a repo id can be as short as `busybox`, `alpine`, or `centos`. These names refer to official images on the public registry. Names can be as long as `my.computers.biz:5043/what/ever` to refer to custom images on an private registry. Often you'll see something like `chef/chef` to refer to private images on the public registry. - Defaults to resource name.
+- `tag` - The second half of a Docker image's identity. - Defaults to `latest`
+- `source` - Path to input for the `:import`, `:build` and `:build_if_missing` actions. For building, this can be a Dockerfile, a tarball containing a Dockerfile in its root, or a directory containing a Dockerfile. For `:import`, this should be a tarball containing Docker formatted image, as generated with `:save`.
+- `destination` - Path for output from the `:save` action.
+- `force` - A force boolean used in various actions - Defaults to false
+- `nocache` - Used in `:build` operations. - Defaults to false
+- `noprune` - Used in `:remove` operations - Defaults to false
+- `rm` - Remove intermediate containers after a successful build (default behavior) - Defaults to `true`
+- `read_timeout` - May need to increase for long image builds/pulls
+- `write_timeout` - May need to increase for long image builds/pulls
+- `host` - A string containing the host the API should communicate with. Defaults to `ENV['DOCKER_HOST']` if set.
+- `tls` - Use TLS; implied by --tlsverify. Defaults to ENV['DOCKER_TLS'] if set.
+- `tls_verify` - Use TLS and verify the remote. Defaults to `ENV['DOCKER_TLS_VERIFY']` if set
+- `tls_ca_cert` - Trust certs signed only by this CA. Defaults to `ENV['DOCKER_CERT_PATH']` if set.
+- `tls_client_cert` - Path to TLS certificate file for docker cli. Defaults to `ENV['DOCKER_CERT_PATH']` if set
+- `tls_client_key` - Path to TLS key file for docker cli. Defaults to `ENV['DOCKER_CERT_PATH']` if set.
+- `buildargs` - A String or Hash containing build arguments.
+
+## Examples
+
+- default action, default properties
+
+```ruby
+docker_image 'hello-world'
+```
+
+- non-default name property
+
+```ruby
+docker_image "Tom's container" do
+  repo 'tduffield/testcontainerd'
+  action :pull
+end
+```
+
+- pull every time
+
+```ruby
+docker_image 'busybox' do
+  action :pull
+end
+```
+
+- specify a tag
+
+```ruby
+docker_image 'alpine' do
+  tag '3.1'
+end
+```
+
+- specify read/write timeouts
+
+```ruby
+docker_image 'alpine' do
+  read_timeout 60
+  write_timeout 60
+end
+```
+
+```ruby
+docker_image 'vbatts/slackware' do
+  action :remove
+end
+```
+
+- save
+
+```ruby
+docker_image 'save hello-world' do
+  repo 'hello-world'
+  destination '/tmp/hello-world.tar'
+  not_if { ::File.exist?('/tmp/hello-world.tar') }
+  action :save
+end
+```
+
+- build from a Dockerfile on every chef-client run
+
+```ruby
+docker_image 'image_1' do
+  tag 'v0.1.0'
+  source '/src/myproject/container1/Dockerfile'
+  action :build
+end
+```
+
+- build from a directory, only if image is missing
+
+```ruby
+docker_image 'image_2' do
+  tag 'v0.1.0'
+  source '/src/myproject/container2'
+  action :build_if_missing
+end
+```
+
+- build from a tarball NOTE: this is not an "export" tarball generated from an image save. The contents should be a Dockerfile, and anything it references to COPY or ADD
+
+```ruby
+docker_image 'image_3' do
+  tag 'v0.1.0'
+  source '/tmp/image_3.tar'
+  action :build
+end
+```
+
+```ruby
+docker_image 'hello-again' do
+  tag 'v0.1.0'
+  source '/tmp/hello-world.tar'
+  action :import
+end
+```
+
+- build from a Dockerfile on every chef-client run with `buildargs`
+
+Acceptable values for `buildargs`:
+
+String:
+
+`buildargs '{"IMAGE_NAME":"alpine","IMAGE_TAG":"latest"}'`
+
+Hash:
+
+`buildargs "IMAGE_NAME": "alpine", "IMAGE_TAG": "latest"`
+
+`buildargs "IMAGE_NAME" => "alpine", "IMAGE_TAG" => "latest"`
+
+```ruby
+docker_image 'image_1' do
+  source '/src/myproject/container1/Dockerfile'
+  buildargs '{"IMAGE_NAME":"alpine","IMAGE_TAG":"latest"}'
+  action :build
+end
+```
+
+Where `Dockerfile` contains:
+
+``` bash
+ARG IMAGE_TAG
+ARG IMAGE_NAME
+FROM $IMAGE_NAME:$IMAGE_TAG
+ARG IMAGE_NAME
+ENV image_name=$IMAGE_NAME
+RUN echo $image_name > /image_name
+```
+
+- push
+
+```ruby
+docker_image 'my.computers.biz:5043/someara/hello-again' do
+  action :push
+end
+```
+
+- Connect to an external docker daemon and pull an image
+
+```ruby
+docker_image 'alpine' do
+  host 'tcp://127.0.0.1:2376'
+  tag '2.7'
+end
+```

documentation/docker_image_prune.md

@@ -0,0 +1,37 @@
+# docker_image_prune
+
+The `docker_image_prune` is responsible for pruning Docker images from the system. It speaks directly to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#operation/ImagePrune).
+Note - this is best implemented by subscribing to `docker_image` changes.  There is no need to to clean up old images upon each converge.  It is best done at the end of a chef run (delayed) only if a new image was pulled.
+
+## Actions
+
+- `:prune` - Delete unused images
+
+## Properties
+
+The `docker_image_prune` resource properties map to filters
+
+- `dangling` - When set to true (or 1), prune only unused and untagged images. When set to false (or 0), all unused images are pruned
+- `prune_until` - Prune images created before this timestamp. The `<timestamp>` can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the daemon machine’s time.
+- `with_label/without_label` -  (`label=<key>`, `label=<key>=<value>`, `label!=<key>`, or `label!=<key>=<value>`) Prune images with (or without, in case label!=... is used) the specified labels.
+- `host` - A string containing the host the API should communicate with. Defaults to `ENV['DOCKER_HOST']` if set.
+
+## Examples
+
+- default action, default properties
+
+```ruby
+docker_image_prune 'prune-old-images'
+```
+
+- All filters
+
+```ruby
+docker_image_prune "prune-old-images" do
+  dangling true
+  prune_until '1h30m'
+  with_label 'com.example.vendor=ACME'
+  without_label 'no_prune'
+  action :prune
+end
+```

documentation/docker_network.md

@@ -0,0 +1,79 @@
+# docker_network
+
+The `docker_network` resource is responsible for managing Docker named networks. Usage of `overlay` driver requires the `docker_service` to be configured to use a distributed key/value store like `etcd`, `consul`, or `zookeeper`.
+
+## Actions
+
+- `:create` - create a network
+- `:delete` - delete a network
+- `:connect` - connect a container to a network
+- `:disconnect` - disconnect a container from a network
+
+## Properties
+
+- `aux_address` - Auxiliary addresses for the network. Ex: `['a=192.168.1.5', 'b=192.168.1.6']`
+- `container` - Container-id/name to be connected/disconnected to/from the network. Used only by `:connect` and `:disconnect` actions
+- `driver` - The network driver to use. Defaults to `bridge`, other options include `overlay`.
+- `enable_ipv6` - Enable IPv6 on the network. Ex: true
+- `gateway` - Specify the gateway(s) for the network. Ex: `192.168.0.1`
+- `ip_range` - Specify a range of IPs to allocate for containers. Ex: `192.168.1.0/24`
+- `subnet` - Specify the subnet(s) for the network. Ex: `192.168.0.0/16`
+
+## Examples
+
+Create a network and use it in a container
+
+```ruby
+docker_network 'network_g' do
+  driver 'overlay'
+  subnet ['192.168.0.0/16', '192.170.0.0/16']
+  gateway ['192.168.0.100', '192.170.0.100']
+  ip_range '192.168.1.0/24'
+  aux_address ['a=192.168.1.5', 'b=192.168.1.6', 'a=192.170.1.5', 'b=192.170.1.6']
+end
+
+docker_container 'echo-base' do
+  repo 'alpine'
+  tag '3.1'
+  command 'nc -ll -p 1337 -e /bin/cat'
+  port '1337'
+  network_mode 'network_g'
+  action :run
+end
+```
+
+Connect to multiple networks
+
+```ruby
+docker_network 'network_h1' do
+  action :create
+end
+
+docker_network 'network_h2' do
+  action :create
+end
+
+docker_container 'echo-base-networks_h' do
+  repo 'alpine'
+  tag '3.1'
+  command 'nc -ll -p 1337 -e /bin/cat'
+  port '1337'
+  network_mode 'network_h1'
+  action :run
+end
+
+docker_network 'network_h2' do
+  container 'echo-base-networks_h'
+  action :connect
+end
+```
+
+IPv6 enabled network
+
+```ruby
+docker_network 'network_i1' do
+  enable_ipv6 true
+  subnet 'fd00:dead:beef::/48'
+  action :create
+end
+```

documentation/docker_plugin.md

@@ -0,0 +1,33 @@
+# docker_plugin
+
+The `docker_plugin` resource allows you to install, configure, enable, disable and remove [Docker Engine managed plugins](https://docs.docker.com/engine/extend/).
+
+## Actions
+
+- `:install` - Install and configure a plugin if it is not already installed
+- `:update` - Re-configure a plugin
+- `:enable` - Enable a plugin (needs to be done after `:install` before it can
+  be used)
+- `:disable` - Disable a plugin (needs to be done before removing a plugin)
+- `:remove` - Remove a disabled plugin
+
+## Properties
+
+- `local_alias` - Local name for the plugin (defaults to the resource name).
+- `remote` - Ref of the plugin (e.g. `vieux/sshfs`). Defaults to `local_alias` or the resource name. Only used for `:install`.
+- `remote_tag` - Remote tag of the plugin to pull (e.g. `1.0.1`, defaults to `latest`) Only used for `:install`.
+- `options` - Hash of options to set on the plugin. Only used for `:update` and `:install`.
+- `grant_privileges` - Array of privileges or true. If it is true, all privileges requested by the plugin will be automatically granted (potentially dangerous). Otherwise, this must be an array in the same format as returned by the [`/plugins/privileges` docker API](https://docs.docker.com/engine/api/v1.37/#operation/GetPluginPrivileges) endpoint. If the array of privileges is not sufficient for the plugin, docker will reject it and the installation will fail. Defaults to `[]` (empty array => no privileges). Only used for `:install`. Does not modify the privileges of already-installed plugins.
+
+## Examples
+
+```ruby
+docker_plugin 'rbd' do
+  remote 'wetopi/rbd'
+  remote_tag '1.0.1'
+  grant_privileges true
+  options(
+    'RBD_CONF_POOL' => 'docker_volumes'
+  )
+end
+```