Refactor documentation for Terraform Registry

.github/workflows/website-test.yml → .github/workflows/docs-lint.yml

@@ -1,14 +1,14 @@
 ---
-name: Website Checks
+name: Documentation Linting
 on:
   pull_request:
     types: ['opened', 'synchronize']
     paths:
-      - 'website/**'
+      - 'docs/**'
       - '.github/workflows/**'
 
 jobs:
-  website-test:
+  docs-lint:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: true
@@ -19,4 +19,4 @@ jobs:
           go-version: '1.14.5'
       - run: bash scripts/gogetcookie.sh
       - run: make tools
-      - run: make website-test
+      - run: make docs-lint

GNUmakefile

@@ -1,5 +1,4 @@
 TEST?=$$(go list ./... |grep -v 'vendor')
-WEBSITE_REPO=github.com/hashicorp/terraform-website
 PKG_NAME=internal
 PROVIDER=azuread
 
@@ -98,30 +97,15 @@ test-compile:
 todo:
 	grep --color=always --exclude=GNUmakefile --exclude-dir=.git --exclude-dir=vendor --line-number --recursive TODO "$(CURDIR)"
 
-website-lint:
+docs-lint:
 	@echo "==> Checking documentation spelling..."
-	@misspell -error -source=text -i hdinsight -locale UK website/
+	@misspell -error -source=text -i hdinsight -locale UK docs/
 	@echo "==> Checking documentation for errors..."
-	@tfproviderdocs check -provider-name=azuread -require-resource-subcategory \
-		-allowed-resource-subcategories-file website/allowed-subcategories
-	@sh -c "'$(CURDIR)/scripts/terrafmt-website.sh'"
-
-website:
-ifeq (,$(wildcard $(GOPATH)/src/$(WEBSITE_REPO)))
-	echo "$(WEBSITE_REPO) not found in your GOPATH (necessary for layouts and assets), get-ting..."
-	git clone https://$(WEBSITE_REPO) $(GOPATH)/src/$(WEBSITE_REPO)
-endif
-	@$(MAKE) -C $(GOPATH)/src/$(WEBSITE_REPO) website-provider PROVIDER_PATH=$(shell pwd) PROVIDER_NAME=$(PKG_NAME)
-
-website-test:
-ifeq (,$(wildcard $(GOPATH)/src/$(WEBSITE_REPO)))
-	echo "$(WEBSITE_REPO) not found in your GOPATH (necessary for layouts and assets), get-ting..."
-	git clone https://$(WEBSITE_REPO) $$(go env GOPATH || $$GOPATH)/src/$(WEBSITE_REPO)
-endif
-	@$(MAKE) -C $$(go env GOPATH || $$GOPATH)/src/$(WEBSITE_REPO) website-provider-test PROVIDER_PATH=$(shell pwd) PROVIDER_NAME=$(PROVIDER)
+	@tfproviderdocs check -provider-name=azuread -allowed-guide-subcategories=Authentication -enable-contents-check -require-schema-ordering -require-guide-subcategory -require-resource-subcategory
+	@sh -c "'$(CURDIR)/scripts/terrafmt-docs.sh'"
 
 teamcity-test:
 	@$(MAKE) -C .teamcity tools
 	@$(MAKE) -C .teamcity test
 
-.PHONY: build test testacc vet fmt fmtcheck errcheck vendor-status test-compile website website-test
+.PHONY: build test testacc vet fmt fmtcheck errcheck vendor-status test-compile

website/docs/d/application.html.markdown → docs/data-sources/application.md

@@ -1,9 +1,5 @@
 ---
-subcategory: "Application"
-layout: "azuread"
-page_title: "Azure Active Directory: azuread_application"
-description: |-
-  Gets information about an existing Application within Azure Active Directory.
+subcategory: "Applications"
 ---
 
 # Data Source: azuread_application
@@ -26,105 +22,75 @@ output "azure_ad_object_id" {
 
 ## Argument Reference
 
-* `object_id` - (Optional) Specifies the Object ID of the Application within Azure Active Directory.
-
 * `application_id` - (Optional) Specifies the Application ID of the Azure Active Directory Application.
-
 * `display_name` - (Optional) Specifies the display name of the Application within Azure Active Directory.
+* `object_id` - (Optional) Specifies the Object ID of the Application within Azure Active Directory.
 
 ~> **NOTE:** One of `object_id`, `application_id` or `display_name` must be specified.
 
 ## Attributes Reference
 
 The following attributes are exported:
 
-* `id` - the Object ID of the Azure Active Directory Application.
-
+* `app_roles` - A collection of `app_role` blocks as documented below. For more information https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles
 * `application_id` - the Application ID of the Azure Active Directory Application.
-
 * `available_to_other_tenants` - Is this Azure AD Application available to other tenants?
-
+* `group_membership_claims` - The `groups` claim issued in a user or OAuth 2.0 access token that the app expects.
+* `id` - the Object ID of the Azure Active Directory Application.
 * `identifier_uris` - A list of user-defined URI(s) that uniquely identify a Web application within it's Azure AD tenant, or within a verified custom domain if the application is multi-tenant.
-
 * `logout_url` - The URL of the logout page.
-
 * `oauth2_allow_implicit_flow` - Does this Azure AD Application allow OAuth2.0 implicit flow tokens?
-
+* `oauth2_permissions` - A collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. Each permission is covered by a `oauth2_permission` block as documented below.
 * `object_id` - the Object ID of the Azure Active Directory Application.
-
-* `reply_urls` - A list of URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to.
-
-* `group_membership_claims` - The `groups` claim issued in a user or OAuth 2.0 access token that the app expects.
-
 * `optional_claims` - A collection of `access_token` or `id_token` blocks as documented below which list the optional claims configured for each token type. For more information see https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-optional-claims
-
 * `owners` - A list of User Object IDs that are assigned ownership of the application registration.
-
-* `required_resource_access` - A collection of `required_resource_access` blocks as documented below.
-
-* `oauth2_permissions` - A collection of OAuth 2.0 permission scopes that the web API (resource) app exposes to client apps. Each permission is covered by a `oauth2_permission` block as documented below.
-
-* `app_roles` - A collection of `app_role` blocks as documented below. For more information https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles
-
 * `public_client` - Is this Azure AD Application available publicly?
+* `reply_urls` - A list of URLs that user tokens are sent to for sign in, or the redirect URIs that OAuth 2.0 authorization codes and access tokens are sent to.
+* `required_resource_access` - A collection of `required_resource_access` blocks as documented below.
 
 ---
 
-`required_resource_access` block exports the following:
-
-* `resource_app_id` - The unique identifier for the resource that the application requires access to.
-
-* `resource_access` - A collection of `resource_access` blocks as documented below
-
----
-
-`resource_access` block exports the following:
+`access_token` and `id_token` blocks export the following:
 
-* `id` - The unique identifier for one of the `OAuth2Permission` or `AppRole` instances that the resource application exposes. 
-
-* `type` - Specifies whether the id property references an `OAuth2Permission` or an `AppRole`.
+* `additional_properties` - List of Additional Properties of the claim. If a property exists in this list, it modifies the behaviour of the optional claim.
+* `essential` - Whether the claim specified by the client is necessary to ensure a smooth authorization experience.
+* `name` - The name of the optional claim.
+* `source` - The source of the claim. If `source` is absent, the claim is a predefined optional claim. If `source` is `user`, the value of `name` is the extension property from the user object.
 
 ---
 
-`access_token` and/or `id_token` blocks export the following:
+`app_role` block exports the following:
 
-* `name` - The name of the optional claim.
-* `source` - The source of the claim. If `source` is absent, the claim is a predefined optional claim. If `source` is `user`, the value of `name` is the extension property from the user object.
-* `essential` - Whether the claim specified by the client is necessary to ensure a smooth authorization experience.
-* `additional_properties` - List of Additional Properties of the claim. If a property exists in this list, it modifies the behaviour of the optional claim.
+* `allowed_member_types` - Specifies whether this app role definition can be assigned to users and groups, or to other applications (that are accessing this application in daemon service scenarios). Possible values are: `User` and `Application`, or both.
+* `description` - Permission help text that appears in the admin app assignment and consent experiences.
+* `display_name` - Display name for the permission that appears in the admin consent and app assignment experiences.
+* `id` - The unique identifier of the `app_role`.
+* `is_enabled` - Determines if the app role is enabled.
+* `value` - Specifies the value of the roles claim that the application should expect in the authentication and access tokens.
 
 ---
 
 `oauth2_permission` block exports the following:
 
-* `id` - The unique identifier for one of the `OAuth2Permission`
-
-* `type` - The type of the permission
-
 * `admin_consent_description` - The description of the admin consent
-
 * `admin_consent_display_name` - The display name of the admin consent
-
+* `id` - The unique identifier for one of the `OAuth2Permission`
 * `is_enabled` - Is this permission enabled?
-
+* `type` - The type of the permission
 * `user_consent_description` - The description of the user consent
-
 * `user_consent_display_name` - The display name of the user consent
-
 * `value` - The name of this permission
 
 ---
 
-`app_role` block exports the following:
-
-* `id` - The unique identifier of the `app_role`.
-
-* `allowed_member_types` - Specifies whether this app role definition can be assigned to users and groups, or to other applications (that are accessing this application in daemon service scenarios). Possible values are: `User` and `Application`, or both.
+`required_resource_access` block exports the following:
 
-* `description` - Permission help text that appears in the admin app assignment and consent experiences.
+* `resource_access` - A collection of `resource_access` blocks as documented below
+* `resource_app_id` - The unique identifier for the resource that the application requires access to.
 
-* `display_name` - Display name for the permission that appears in the admin consent and app assignment experiences.
+---
 
-* `is_enabled` - Determines if the app role is enabled.
+`resource_access` block exports the following:
 
-* `value` - Specifies the value of the roles claim that the application should expect in the authentication and access tokens.
+* `id` - The unique identifier for one of the `OAuth2Permission` or `AppRole` instances that the resource application exposes. 
+* `type` - Specifies whether the id property references an `OAuth2Permission` or an `AppRole`.

website/docs/d/client_config.html.markdown → docs/data-sources/client_config.md

@@ -1,9 +1,5 @@
 ---
 subcategory: "Base"
-layout: "azuread"
-page_title: "Azure Active Directory: azuread_client_config"
-description: |-
-  Gets information about the configuration of the AzureAD provider.
 ---
 
 # Data Source: azuread_client_config
@@ -28,5 +24,5 @@ There are no arguments available for this data source.
 ## Attributes Reference
 
 * `client_id` is set to the Client ID (Application ID).
-* `tenant_id` is set to the Tenant ID.
 * `object_id` is set to the Object ID of the authenticated principal.
+* `tenant_id` is set to the Tenant ID.

website/docs/d/domains.html.markdown → docs/data-sources/domains.md

@@ -1,9 +1,5 @@
 ---
 subcategory: "Domains"
-layout: "azuread"
-page_title: "Azure Active Directory: azuread_domains"
-description: |-
-  Gets information about existing Domains within Azure Active Directory.
 ---
 
 # Data Source: azuread_domains
@@ -32,12 +28,12 @@ output "domains" {
 
 ## Attributes Reference
 
-* `domains` - One or more `domain` blocks as defined below.
+* `domains` - A list of domains. Each `domain` object provides the attributes documented below.
 
-The `domain` block contains:
+`domain` object exports the following:
 
-* `domain_name` - The name of the domain.
 * `authentication_type` - The authentication type of the domain (Managed or Federated).
+* `domain_name` - The name of the domain.
 * `is_default` - `True` if this is the default domain that is used for user creation.
 * `is_initial` - `True` if this is the initial domain created by Azure Active Directory.
 * `is_verified` - `True` if the domain has completed domain ownership verification.

website/docs/d/group.html.markdown → docs/data-sources/group.md

@@ -1,10 +1,5 @@
 ---
 subcategory: "Groups"
-layout: "azuread"
-page_title: "Azure Active Directory: azuread_group"
-description: |-
-  Gets information about an Azure Active Directory group.
-
 ---
 
 # Data Source: azuread_group
@@ -26,7 +21,6 @@ data "azuread_group" "example" {
 The following arguments are supported:
 
 * `display_name` - (Optional) The splay name of the Group within Azure Active Directory.
-
 * `object_id` - (Optional) Specifies the Object ID of the Group within Azure Active Directory.
 
 ~> **NOTE:** One of `display_name` or `object_id` must be specified.
@@ -35,9 +29,9 @@ The following arguments are supported:
 
 The following attributes are exported:
 
-* `id` - The Object ID of the Azure AD Group.
 * `description` - The description of the AD Group.
 * `display_name` - The name of the Azure AD Group.
-* `owners` - The Object IDs of the Azure AD Group owners.
+* `id` - The Object ID of the Azure AD Group.
 * `members` - The Object IDs of the Azure AD Group members.
+* `owners` - The Object IDs of the Azure AD Group owners.
 

website/docs/d/groups.html.markdown → docs/data-sources/groups.md

@@ -1,10 +1,5 @@
 ---
 subcategory: "Groups"
-layout: "azuread"
-page_title: "Azure Active Directory: azuread_groups"
-description: |-
-  Gets information about Azure Active Directory groups.
-
 ---
 
 # Data Source: azuread_groups
@@ -26,7 +21,6 @@ data "azuread_groups" "groups" {
 The following arguments are supported:
 
 * `names` - (Optional) The Display Names of the Azure AD Groups.
-
 * `object_ids` - (Optional) The Object IDs of the Azure AD Groups.
 
 ~> **NOTE:** Either `names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned.
@@ -35,5 +29,5 @@ The following arguments are supported:
 
 The following attributes are exported:
 
-* `object_ids` - The Object IDs of the Azure AD Groups.
 * `names` - The Display Names of the Azure AD Groups.
+* `object_ids` - The Object IDs of the Azure AD Groups.