docs: refactor plugin properties

_docs/content/_index.md

@@ -21,6 +21,30 @@ Drone plugin to build and publish multiarch Docker images.
 
 The tags follow the major version of Docker, e.g. `19`, the minor and patch part reflects the "version" of the plugin. A full example would be `19.6.5`. Minor versions may introduce breaking changes, while patch versions may be considered non-breaking.
 
+## Usage
+
+```YAML
+kind: pipeline
+name: default
+
+steps:
+  - name: docker
+    image: thegeeklab/drone-docker
+    settings:
+      username: octocat
+      password: secure
+      repo: octocat/example
+      tags: latest
+```
+
+### Parameters
+
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< propertylist name=drone-docker.data >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
+
 ## Build
 
 Build the binary with the following command:
@@ -40,7 +64,7 @@ Build the Docker image with the following command:
 docker build --file docker/Dockerfile.amd64 --tag thegeeklab/drone-docker .
 ```
 
-## Usage
+## Test
 
 {{< hint type=important >}}
 Be aware that the this plugin requires privileged capabilities, otherwise the integrated Docker daemon is not able to start.
@@ -56,110 +80,3 @@ docker run --rm \
   --privileged \
   thegeeklab/drone-docker --dry-run
 ```
-
-### Parameters
-
-dry_run
-: disables docker push
-
-drone_remote_url
-: sets the git remote url
-
-mirror
-: sets a registry mirror to pull images
-
-storage_driver
-: sets the docker daemon storage driver
-
-storage_path
-: sets the docker daemon storage path (default `/var/lib/docker`)
-
-bip
-: allows the docker daemon to bride ip address
-
-mtu
-: sets docker daemon custom mtu setting
-
-custom_dns
-: sets custom docker daemon dns server
-
-custom_dns_search
-: sets custom docker daemon dns search domain
-
-insecure
-: allows the docker daemon to use insecure registries
-
-ipv6
-: enables docker daemon ipv6 support
-
-experimental
-: enables docker daemon experimental mode
-
-debug "docker_launch_debug
-: enables verbose debug mode for the docker daemon
-
-daemon_off
-: disables the startup of the docker daemon
-
-dockerfile
-: sets dockerfile to use for the image build (default `./Dockerfile`)
-
-context
-: sets the path of the build context to use (default `./`)
-
-tags
-: sets repository tags to use for the image; tags can also be loaded from a `.tags` file (default `latest`)
-
-auto_tag
-: generates tag names automatically based on git branch and git tag
-
-auto_tag_suffix
-: generates tag names with the given suffix
-
-build_args
-: sets custom build arguments for the build
-
-build_args_from_env
-: forwards environment variables as custom arguments to the build
-
-quiet
-: enables suppression of the build output
-
-target
-: sets the build target to use
-
-cache_from
-: sets images to consider as cache sources
-
-pull_image
-: enforces to pull base image at build time (default `true`)
-
-compress
-: enables compression og the build context using gzip
-
-repo
-: sets repository name for the image
-
-registry
-: sets docker registry to authenticate with (default `https://index.docker.io/v1/`)
-
-username
-: sets username to authenticates with
-
-password
-: sets password to authenticates with
-
-email
-: sets email address to authenticates with
-
-config
-: sets content of the docker daemon json config
-
-purge
-: enables cleanup of the docker environment at the end of a build (default `true`)
-
-no_cache
-: disables the usage of cached intermediate containers
-
-add_host
-: sets additional host:ip mapping

_docs/data/data.yaml

@@ -0,0 +1,200 @@
+---
+parameters:
+  dry_run:
+    description: Disable docker push.
+    type: bool
+    required: false
+
+  drone_remote_url:
+    description: The git remote url.
+    type: string
+    required: false
+
+  mirror:
+    description: Use a registry mirror to pull images.
+    type: string
+    required: false
+
+  storage_driver:
+    description: The docker daemon storage driver.
+    type: string
+    required: false
+
+  storage_path:
+    description: The docker daemon storage path.
+    defaultValue: /var/lib/docker
+    type: string
+    required: false
+
+  bip:
+    description: Allows the docker daemon to bride IP address.
+    type: string
+    required: false
+
+  mtu:
+    description: A docker daemon custom MTU.
+    type: string
+    required: false
+
+  custom_dns:
+    description: Custom docker daemon DNS server.
+    type: list
+    required: false
+
+  custom_dns_search:
+    description: Custom docker daemon DNS search domain.
+    type: list
+    required: false
+
+  insecure:
+    description: Enable the usage of insecure registries.
+    type: bool
+    defaultValue: false
+    required: false
+
+  ipv6:
+    description: Enable docker daemon IPv6 support.
+    type: bool
+    defaultValue: false
+    required: false
+
+  experimental:
+    description: Enable docker daemon experimental mode.
+    type: bool
+    defaultValue: false
+    required: false
+
+  daemon_debug:
+    description: Enable verbose debug mode for the docker daemon.
+    type: string
+    defaultValue: false
+    required: false
+
+  daemon_off:
+    description: Disable the startup of the docker daemon.
+    type: string
+    defaultValue: false
+    required: false
+
+  dockerfile:
+    description: Set dockerfile to use for the image build.
+    defaultValue: Dockerfile
+    type: string
+    required: false
+
+  context:
+    description: Set the path of the build context to use.
+    defaultValue: .
+    type: string
+    required: false
+
+  tags:
+    description: Set repository tags to use for the image. Tags can also be loaded from a `.tags` file.
+    defaultValue: latest
+    type: list
+    required: false
+
+  auto_tag:
+    description: >
+      Generate tag names automatically based on git branch and git tag. When this feature is enabled and the event type is `tag`,
+      the plugin will automatically tag the image using the standard semVer convention. For example:
+
+      - `1.0.0` produces docker tags `1`, `1.0`, `1.0.0`
+      - `1.0.0-rc.1` produces docker tags `1.0.0-rc.1`
+
+      When the event type is `push` and the target branch is your default branch, the plugin will automatically tag the image
+      as `latest`. All other event types and branches are ignored.
+    defaultValue: false
+    type: bool
+    required: false
+
+  auto_tag_suffix:
+    description: Generate tag names with the given suffix.
+    type: string
+    required: false
+
+  build_args:
+    description: Ccustom build arguments to pass to the build.
+    type: list
+    required: false
+
+  build_args_from_env:
+    description: Forward environment variables as custom arguments to the build.
+    type: list
+    required: false
+
+  quiet:
+    description: Enable suppression of the build output.
+    defaultValue: false
+    type: bool
+    required: false
+
+  target:
+    description: The docker build target.
+    type: string
+    required: false
+
+  cache_from:
+    description: Images to consider as cache sources.
+    type: list
+    required: false
+
+  pull_image:
+    description: Enforce to pull the base image at build time.
+    defaultValue: true
+    type: bool
+    required: false
+
+  compress:
+    description: Enable compression og the build context using gzip.
+    defaultValue: false
+    type: bool
+    required: false
+
+  repo:
+    description: Repository name for the image.
+    type: string
+    required: false
+
+  registry:
+    description: Docker registry to upload images.
+    defaultValue: https://index.docker.io/v1/
+    type: string
+    required: false
+
+  username:
+    description: Username for authentication with the registry.
+    type: string
+    required: false
+
+  password:
+    description: Password for authentication with the registry.
+    type: string
+    required: false
+
+  email:
+    description: E-Mail address for authentication with the registry.
+    type: string
+    required: false
+
+  config:
+    description: Content of the docker daemon json config.
+    type: string
+    required: false
+
+  purge:
+    description: Enable cleanup of the docker environment at the end of a build.
+    defaultValue: true
+    type: bool
+    required: false
+
+  no_cache:
+    description: Disable the usage of cached intermediate containers.
+    defaultValue: false
+    type: string
+    required: false
+
+  add_host:
+    description: Additional `host:ip` mapping.
+    type: list
+    required: false

cmd/drone-docker/config.go

@@ -11,35 +11,35 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.BoolFlag{
 			Name:        "dry-run",
 			EnvVars:     []string{"PLUGIN_DRY_RUN"},
-			Usage:       "disables docker push",
+			Usage:       "disable docker push",
 			Destination: &settings.Dryrun,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "remote.url",
 			EnvVars:     []string{"DRONE_REMOTE_URL"},
-			Usage:       "sets the git remote url",
+			Usage:       "git remote url",
 			Destination: &settings.Build.Remote,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "daemon.mirror",
 			EnvVars:     []string{"PLUGIN_MIRROR", "DOCKER_PLUGIN_MIRROR"},
-			Usage:       "sets a registry mirror to pull images",
+			Usage:       "registry mirror to pull images",
 			Destination: &settings.Daemon.Mirror,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "daemon.storage-driver",
 			EnvVars:     []string{"PLUGIN_STORAGE_DRIVER"},
-			Usage:       "sets the docker daemon storage driver",
+			Usage:       "docker daemon storage driver",
 			Destination: &settings.Daemon.StorageDriver,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "daemon.storage-path",
 			EnvVars:     []string{"PLUGIN_STORAGE_PATH"},
-			Usage:       "sets the docker daemon storage path",
+			Usage:       "docker daemon storage path",
 			Value:       "/var/lib/docker",
 			Destination: &settings.Daemon.StoragePath,
 			Category:    category,
@@ -47,70 +47,75 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "daemon.bip",
 			EnvVars:     []string{"PLUGIN_BIP"},
-			Usage:       "allows the docker daemon to bride ip address",
+			Usage:       "allow the docker daemon to bride ip address",
 			Destination: &settings.Daemon.Bip,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "daemon.mtu",
 			EnvVars:     []string{"PLUGIN_MTU"},
-			Usage:       "sets docker daemon custom mtu setting",
+			Usage:       "docker daemon custom mtu setting",
 			Destination: &settings.Daemon.MTU,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "daemon.dns",
 			EnvVars:     []string{"PLUGIN_CUSTOM_DNS"},
-			Usage:       "sets custom docker daemon dns server",
+			Usage:       "custom docker daemon dns server",
 			Destination: &settings.Daemon.DNS,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "daemon.dns-search",
 			EnvVars:     []string{"PLUGIN_CUSTOM_DNS_SEARCH"},
-			Usage:       "sets custom docker daemon dns search domain",
+			Usage:       "custom docker daemon dns search domain",
 			Destination: &settings.Daemon.DNSSearch,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "daemon.insecure",
 			EnvVars:     []string{"PLUGIN_INSECURE"},
-			Usage:       "allows the docker daemon to use insecure registries",
+			Usage:       "allow the docker daemon to use insecure registries",
+			Value:       false,
 			Destination: &settings.Daemon.Insecure,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "daemon.ipv6",
 			EnvVars:     []string{"PLUGIN_IPV6"},
-			Usage:       "enables docker daemon IPv6 support",
+			Usage:       "enable docker daemon IPv6 support",
+			Value:       false,
 			Destination: &settings.Daemon.IPv6,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "daemon.experimental",
 			EnvVars:     []string{"PLUGIN_EXPERIMENTAL"},
-			Usage:       "enables docker daemon experimental mode",
+			Usage:       "enable docker daemon experimental mode",
+			Value:       false,
 			Destination: &settings.Daemon.Experimental,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "daemon.debug",
 			EnvVars:     []string{"PLUGIN_DEBUG", "DOCKER_LAUNCH_DEBUG"},
-			Usage:       "enables verbose debug mode for the docker daemon",
+			Usage:       "enable verbose debug mode for the docker daemon",
+			Value:       false,
 			Destination: &settings.Daemon.Debug,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "daemon.off",
 			EnvVars:     []string{"PLUGIN_DAEMON_OFF"},
-			Usage:       "disables the startup of the docker daemon",
+			Usage:       "disable the startup of the docker daemon",
+			Value:       false,
 			Destination: &settings.Daemon.Disabled,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "dockerfile",
 			EnvVars:     []string{"PLUGIN_DOCKERFILE"},
-			Usage:       "sets dockerfile to use for the image build",
+			Usage:       "dockerfile to use for the image build",
 			Value:       "Dockerfile",
 			Destination: &settings.Build.Dockerfile,
 			Category:    category,
@@ -118,7 +123,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "context",
 			EnvVars:     []string{"PLUGIN_CONTEXT"},
-			Usage:       "sets the path of the build context to use",
+			Usage:       "path of the build context",
 			Value:       ".",
 			Destination: &settings.Build.Context,
 			Category:    category,
@@ -126,7 +131,7 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringSliceFlag{
 			Name:        "tags",
 			EnvVars:     []string{"PLUGIN_TAG", "PLUGIN_TAGS"},
-			Usage:       "sets repository tags to use for the image",
+			Usage:       "repository tags to use for the image",
 			FilePath:    ".tags",
 			Destination: &settings.Build.Tags,
 			Category:    category,
@@ -134,56 +139,58 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.BoolFlag{
 			Name:        "tags.auto",
 			EnvVars:     []string{"PLUGIN_DEFAULT_TAGS", "PLUGIN_AUTO_TAG"},
-			Usage:       "generates tag names automatically based on git branch and git tag",
+			Usage:       "generate tag names automatically based on git branch and git tag",
+			Value:       false,
 			Destination: &settings.Build.TagsAuto,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "tags.suffix",
 			EnvVars:     []string{"PLUGIN_DEFAULT_SUFFIX", "PLUGIN_AUTO_TAG_SUFFIX"},
-			Usage:       "generates tag names with the given suffix",
+			Usage:       "generate tag names with the given suffix",
 			Destination: &settings.Build.TagsSuffix,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "args",
 			EnvVars:     []string{"PLUGIN_BUILD_ARGS"},
-			Usage:       "sets custom build arguments for the build",
+			Usage:       "custom build arguments for the build",
 			Destination: &settings.Build.Args,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "args-from-env",
 			EnvVars:     []string{"PLUGIN_BUILD_ARGS_FROM_ENV"},
-			Usage:       "forwards environment variables as custom arguments to the build",
+			Usage:       "forward environment variables as custom arguments to the build",
 			Destination: &settings.Build.ArgsEnv,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "quiet",
 			EnvVars:     []string{"PLUGIN_QUIET"},
-			Usage:       "enables suppression of the build output",
+			Usage:       "enable suppression of the build output",
+			Value:       false,
 			Destination: &settings.Build.Quiet,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "target",
 			EnvVars:     []string{"PLUGIN_TARGET"},
-			Usage:       "sets the build target to use",
+			Usage:       "build target to use",
 			Destination: &settings.Build.Target,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "cache-from",
 			EnvVars:     []string{"PLUGIN_CACHE_FROM"},
-			Usage:       "sets images to consider as cache sources",
+			Usage:       "images to consider as cache sources",
 			Destination: &settings.Build.CacheFrom,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "pull-image",
 			EnvVars:     []string{"PLUGIN_PULL_IMAGE"},
-			Usage:       "enforces to pull base image at build time",
+			Usage:       "enforce to pull base image at build time",
 			Value:       true,
 			Destination: &settings.Build.Pull,
 			Category:    category,
@@ -191,21 +198,22 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.BoolFlag{
 			Name:        "compress",
 			EnvVars:     []string{"PLUGIN_COMPRESS"},
-			Usage:       "enables compression og the build context using gzip",
+			Usage:       "enable compression og the build context using gzip",
+			Value:       false,
 			Destination: &settings.Build.Compress,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "repo",
 			EnvVars:     []string{"PLUGIN_REPO"},
-			Usage:       "sets repository name for the image",
+			Usage:       "repository name for the image",
 			Destination: &settings.Build.Repo,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "docker.registry",
 			EnvVars:     []string{"PLUGIN_REGISTRY", "DOCKER_REGISTRY"},
-			Usage:       "sets docker registry to authenticate with",
+			Usage:       "docker registry to authenticate with",
 			Value:       "https://index.docker.io/v1/",
 			Destination: &settings.Login.Registry,
 			Category:    category,
@@ -213,35 +221,35 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.StringFlag{
 			Name:        "docker.username",
 			EnvVars:     []string{"PLUGIN_USERNAME", "DOCKER_USERNAME"},
-			Usage:       "sets username to authenticates with",
+			Usage:       "username for registry authentication",
 			Destination: &settings.Login.Username,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "docker.password",
 			EnvVars:     []string{"PLUGIN_PASSWORD", "DOCKER_PASSWORD"},
-			Usage:       "sets password to authenticates with",
+			Usage:       "password for registry authentication",
 			Destination: &settings.Login.Password,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "docker.email",
 			EnvVars:     []string{"PLUGIN_EMAIL", "DOCKER_EMAIL"},
-			Usage:       "sets email address to authenticates with",
+			Usage:       "email address for registry authentication",
 			Destination: &settings.Login.Email,
 			Category:    category,
 		},
 		&cli.StringFlag{
 			Name:        "docker.config",
 			EnvVars:     []string{"PLUGIN_CONFIG", "DOCKER_PLUGIN_CONFIG"},
-			Usage:       "sets content of the docker daemon json config",
+			Usage:       "content of the docker daemon json config",
 			Destination: &settings.Login.Config,
 			Category:    category,
 		},
 		&cli.BoolFlag{
 			Name:        "docker.purge",
 			EnvVars:     []string{"PLUGIN_PURGE"},
-			Usage:       "enables cleanup of the docker environment at the end of a build",
+			Usage:       "enable cleanup of the docker environment at the end of a build",
 			Value:       true,
 			Destination: &settings.Cleanup,
 			Category:    category,
@@ -249,14 +257,15 @@ func settingsFlags(settings *plugin.Settings, category string) []cli.Flag {
 		&cli.BoolFlag{
 			Name:        "no-cache",
 			EnvVars:     []string{"PLUGIN_NO_CACHE"},
-			Usage:       "disables the usage of cached intermediate containers",
+			Usage:       "disable the usage of cached intermediate containers",
+			Value:       false,
 			Destination: &settings.Build.NoCache,
 			Category:    category,
 		},
 		&cli.StringSliceFlag{
 			Name:        "add-host",
 			EnvVars:     []string{"PLUGIN_ADD_HOST"},
-			Usage:       "sets additional host:ip mapping",
+			Usage:       "additional host:ip mapping",
 			Destination: &settings.Build.AddHost,
 			Category:    category,
 		},