Merge pull request #654 from willianpaixao/master

More examples and better documentation

Author: armsnyder

docs/data-sources/user.md

@@ -1,6 +1,6 @@
 # gitlab\_user
 
-Provides details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
+Provide details about a specific user in the gitlab provider. Especially the ability to lookup the id for linking to other resources.
 
 ## Example Usage
 
@@ -10,6 +10,16 @@ data "gitlab_user" "example" {
 }
 ```
 
+### Example using `for_each`
+
+```hcl
+data "gitlab_user" "example-two" {
+  for_each = toset(["user1", "user2", "user3"])
+
+  username = each.value
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
@@ -20,7 +30,7 @@ The following arguments are supported:
 
 * `user_id` - (Optional) The ID of the user.
 
-**Note**: only one of email, user_id or username must be provided.
+-> Only one of email, user_id, or username must be provided.
 
 ## Attributes Reference
 
@@ -52,7 +62,7 @@ The following arguments are supported:
 
 * `organization` - The organization of the user.
 
-* `two_factor_enabled` - Whether user's two factor auth is enabled.
+* `two_factor_enabled` - Whether user's two-factor auth is enabled.
 
 * `avatar_url` - The avatar URL of the user.
 
@@ -62,7 +72,7 @@ The following arguments are supported:
 
 * `skype` - Skype username of the user.
 
-* `linkedin` - Linkedin profile of the user.
+* `linkedin` - LinkedIn profile of the user.
 
 * `twitter` - Twitter username of the user.
 
@@ -76,6 +86,4 @@ The following arguments are supported:
 
 * `current_sign_in_at` - Current user's sign-in date.
 
-**Note**: some attributes might not be returned depending on if you're an admin or not. Please refer to [doc][doc] for more details.
-
-[doc]: https://docs.gitlab.com/ce/api/users.html#single-user
+-> Some attributes might not be returned depending on if you're an admin or not. Please refer to [Gitlab documentation](https://docs.gitlab.com/ce/api/users.html#single-user) for more details.

docs/resources/branch_protection.md

@@ -2,7 +2,7 @@
 
 This resource allows you to protect a specific branch by an access level so that the user with less access level cannot Merge/Push to the branch.
 
--> The `allowed_to_push`, `allowed_to_merge` and `code_owner_approval_required` arguments require a GitLab Premium account or above.
+-> The `allowed_to_push`, `allowed_to_merge` and `code_owner_approval_required` arguments require a GitLab Premium account or above.  Please refer to [Gitlab API documentation](https://docs.gitlab.com/ee/api/protected_branches.html) for further information.
 
 ## Example Usage
 
@@ -28,6 +28,24 @@ resource "gitlab_branch_protection" "BranchProtect" {
 }
 ```
 
+### Example using dynamic block
+
+```hcl
+resource "gitlab_branch_protection" "main" {
+  project                      = "12345"
+  branch                       = "main"
+  push_access_level            = "maintainer"
+  merge_access_level           = "maintainer"
+
+  dynamic "allowed_to_push" {
+    for_each = [50, 55, 60]
+    content {
+      user_id = allowed_to_push.value
+    }
+  }
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
@@ -62,7 +80,7 @@ The following attributes are exported:
 
 ## Import
 
-GitLab project freeze periods can be imported using an id made up of `project_id:branch`, e.g.
+Gitlab protected branches can be imported with a key composed of `<project_id>:<branch>`, e.g.
 
 ```
 $ terraform import gitlab_branch_protection.BranchProtect "12345:main"

docs/resources/deploy_token.md

@@ -1,6 +1,6 @@
 # gitlab\_deploy\_token
 
-This resource allows you to create and manage deploy token for your GitLab projects and groups.
+This resource allows you to create and manage deploy token for your GitLab projects and groups. Please refer to [Gitlab documentation](https://docs.gitlab.com/ee/user/project/deploy_tokens/) for further information.
 
 ## Example Usage - Project
 
@@ -13,6 +13,12 @@ resource "gitlab_deploy_token" "example" {
   
   scopes = [ "read_repository", "read_registry" ]
 }
+
+resource "gitlab_deploy_token" "example-two" {
+  project    = "12345678"
+  name       = "Example deploy token expires in 24h"
+  expires_at = timeadd(timestamp(), "24h")
+}
 ```
 
 ## Example Usage - Group
@@ -21,7 +27,7 @@ resource "gitlab_deploy_token" "example" {
 resource "gitlab_deploy_token" "example" {
   group      = "example/deploying"
   name       = "Example group deploy token"
-  
+
   scopes = [ "read_repository" ]
 }
 ```

docs/resources/project_approval_rule.md

@@ -1,8 +1,6 @@
 # gitlab\_project\_approval\_rule
 
-This resource allows you to create and manage multiple approval rules for your GitLab
-projects. For further information on approval rules, consult the [gitlab
-documentation](https://docs.gitlab.com/ee/api/merge_request_approvals.html#project-level-mr-approvals).
+This resource allows you to create and manage multiple approval rules for your GitLab projects. For further information on approval rules, consult the [gitlab documentation](https://docs.gitlab.com/ee/api/merge_request_approvals.html#project-level-mr-approvals).
 
 -> This feature requires GitLab Premium.
 
@@ -28,16 +26,33 @@ resource "gitlab_branch_protection" "example" {
   merge_access_level = "developer"
 }
 
-resource "gitlab_project_approval_rule" "example" {
+resource "gitlab_project_approval_rule" "example-two" {
   project              = 5
-  name                 = "Example Rule"
+  name                 = "Example Rule 2"
   approvals_required   = 3
   user_ids             = [50, 500]
   group_ids            = [51]
   protected_branch_ids = [gitlab_branch_protection.example.branch_protection_id]
 }
 ```
 
+### Example using `data.gitlab_user` and `for` loop
+
+```hcl
+data "gitlab_user" "users" {
+  for_each = toset(["user1", "user2", "user3"])
+
+  username = each.value
+}
+
+resource "gitlab_project_approval_rule" "example-three" {
+  project            = 5
+  name               = "Example Rule 3"
+  approvals_required = 3
+  user_ids           = [for user in data.gitlab_user.users : user.id]
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
@@ -56,7 +71,7 @@ The following arguments are supported:
 
 ## Import
 
-GitLab project approval rules can be imported using an id consisting of `project-id:rule-id`, e.g.
+GitLab project approval rules can be imported using a key composed of `<project-id>:<rule-id>`, e.g.
 
 ```
 $ terraform import gitlab_project_approval_rule.example "12345:6"

docs/resources/project_level_mr_approvals.md

@@ -1,8 +1,7 @@
 # gitlab\_project\_level\_mr\_approvals
 
 This resource allows you to configure project-level MR approvals. for your GitLab projects.
-For further information on merge request approvals, consult the [GitLab API
-documentation](https://docs.gitlab.com/ee/api/merge_request_approvals.html#project-level-mr-approvals).
+For further information on merge request approvals, consult the [GitLab API documentation](https://docs.gitlab.com/ee/api/merge_request_approvals.html#project-level-mr-approvals).
 
 ## Example Usage
 
@@ -39,10 +38,10 @@ also need to be included in the approvers list in order to be able to approve th
 
 ## Import
 
-You can import an approval configuration state using `terraform import <resource> <project_id>`.
+You can import an approval configuration state using `terraform import <resource> <project_id>:<approval_rule_id>`.
 
 For example:
 
 ```
-$ terraform import gitlab_project_level_mr_approvals.foo 53
+$ terraform import gitlab_project_level_mr_approvals.foo 1234:53
 ```

docs/resources/user.md

@@ -3,7 +3,7 @@
 This resource allows you to create and manage GitLab users.
 Note your provider will need to be configured with admin-level access for this resource to work.
 
--> **Note:** You must specify either `password` or `reset_password`.
+-> You must specify either `password` or `reset_password`.
 
 ## Example Usage
 
@@ -33,7 +33,7 @@ The following arguments are supported:
 
 * `password` - (Optional) The password of the user.
 
-* `is_admin` - (Optional) Boolean, defaults to false.  Whether to enable administrative priviledges
+* `is_admin` - (Optional) Boolean, defaults to false.  Whether to enable administrative privileges
 for the user.
 
 * `projects_limit` - (Optional) Integer, defaults to 0.  Number of projects user can create.