From 208b733baeeb4d1000ecee53d96b87da957f6091 Mon Sep 17 00:00:00 2001 From: Manuel Vogel Date: Thu, 13 May 2021 08:40:54 +0200 Subject: [PATCH] docs(network): update ds descriptions --- docs/data-sources/network.md | 22 ++++--- docs/index.md | 16 +++++ examples/README.md | 9 +++ .../docker_network/data-source.tf | 3 + examples/provider/provider.tf | 13 ++++ .../provider/data_source_docker_network.go | 60 +++++++++++-------- 6 files changed, 91 insertions(+), 32 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/data-sources/docker_network/data-source.tf create mode 100644 examples/provider/provider.tf diff --git a/docs/data-sources/network.md b/docs/data-sources/network.md index 9e694659..c4c92009 100644 --- a/docs/data-sources/network.md +++ b/docs/data-sources/network.md @@ -3,14 +3,20 @@ 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 @@ -18,15 +24,15 @@ description: |- ### Optional - **id** (String) The ID of this resource. -- **name** (String) +- **name** (String) The name of the Docker network. ### Read-Only -- **driver** (String) -- **internal** (Boolean) -- **ipam_config** (Set of Object) (see [below for nested schema](#nestedatt--ipam_config)) -- **options** (Map of String) -- **scope** (String) +- **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. +- **internal** (Boolean) Whether the network is internal. +- **ipam_config** (Set of Object) 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`. ### Nested Schema for `ipam_config` diff --git a/docs/index.md b/docs/index.md index 5f842a4b..20f9ddeb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,23 @@ description: |- +## Example Usage +```terraform +provider "docker" { + host = "tcp://127.0.0.1:2376/" +} + +# Create a container +resource "docker_container" "foo" { + image = docker_image.ubuntu.latest + name = "foo" +} + +resource "docker_image" "ubuntu" { + name = "ubuntu:latest" +} +``` ## Schema diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..e77755a3 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,9 @@ +# Examples + +This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. + +The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation. + +* **provider/provider.tf** example file for the provider index page +* **data-sources//data-source.tf** example file for the named data source page +* **resources//resource.tf** example file for the named data source page \ No newline at end of file diff --git a/examples/data-sources/docker_network/data-source.tf b/examples/data-sources/docker_network/data-source.tf new file mode 100644 index 00000000..6c8aff86 --- /dev/null +++ b/examples/data-sources/docker_network/data-source.tf @@ -0,0 +1,3 @@ +data "docker_network" "main" { + name = "main" +} diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf new file mode 100644 index 00000000..c5035e06 --- /dev/null +++ b/examples/provider/provider.tf @@ -0,0 +1,13 @@ +provider "docker" { + host = "tcp://127.0.0.1:2376/" +} + +# Create a container +resource "docker_container" "foo" { + image = docker_image.ubuntu.latest + name = "foo" +} + +resource "docker_image" "ubuntu" { + name = "ubuntu:latest" +} diff --git a/internal/provider/data_source_docker_network.go b/internal/provider/data_source_docker_network.go index 44267d9f..65a9ec85 100644 --- a/internal/provider/data_source_docker_network.go +++ b/internal/provider/data_source_docker_network.go @@ -12,12 +12,15 @@ import ( func dataSourceDockerNetwork() *schema.Resource { return &schema.Resource{ + Description: "`docker_network` provides details about a specific Docker Network.", + ReadContext: dataSourceDockerNetworkRead, Schema: map[string]*schema.Schema{ "name": { - Type: schema.TypeString, - Optional: true, + Type: schema.TypeString, + Description: "The name of the Docker network.", + Optional: true, }, "id": { @@ -26,55 +29,64 @@ func dataSourceDockerNetwork() *schema.Resource { }, "driver": { - Type: schema.TypeString, - Computed: true, + Type: schema.TypeString, + Description: "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.", + Computed: true, }, "options": { - Type: schema.TypeMap, - Computed: true, + Type: schema.TypeMap, + Description: "Only available with bridge networks. See [bridge options docs](https://docs.docker.com/engine/reference/commandline/network_create/#bridge-driver-options) for more details.", + Computed: true, }, "internal": { - Type: schema.TypeBool, - Computed: true, + Type: schema.TypeBool, + Description: "Whether the network is internal.", + Computed: true, }, "ipam_config": { - Type: schema.TypeSet, - Computed: true, + Type: schema.TypeSet, + Description: "IPAM configuration options", + Computed: true, Elem: &schema.Resource{ Schema: map[string]*schema.Schema{ "subnet": { - Type: schema.TypeString, - Optional: true, - ForceNew: true, + Type: schema.TypeString, + Description: "The subnet in CIDR form", + Optional: true, + ForceNew: true, }, "ip_range": { - Type: schema.TypeString, - Optional: true, - ForceNew: true, + Type: schema.TypeString, + Description: "The ip range in CIDR form", + Optional: true, + ForceNew: true, }, "gateway": { - Type: schema.TypeString, - Optional: true, - ForceNew: true, + Type: schema.TypeString, + Description: "The IP address of the gateway", + Optional: true, + ForceNew: true, }, "aux_address": { - Type: schema.TypeMap, - Optional: true, - ForceNew: true, + Type: schema.TypeMap, + Description: "Auxiliary IPv4 or IPv6 addresses used by Network driver", + Optional: true, + ForceNew: true, }, }, }, }, "scope": { - Type: schema.TypeString, - Computed: true, + Type: schema.TypeString, + Description: "Scope of the network. One of `swarm`, `global`, or `local`.", + Computed: true, }, }, }