[MAINT] Migrate to use tfplugindocs for managing docs

.github/workflows/ci.yml

@@ -25,7 +25,15 @@ jobs:
           cache: true
       - run: make tools
       - run: make lint
-      - run: make website-lint
+      - run: make docs-lint
+
+      - name: Check for uncommitted docs changes
+        run: |
+          tfplugindocs generate
+          if ! [[ -z $(git status --porcelain) ]]; then
+            echo "::error::Uncommitted changes after tfplugindocs generate"
+            exit 1
+          fi
       - run: make build
       - run: make test
 

.markdownlint.json

@@ -0,0 +1,17 @@
+{
+  "MD004": {
+    "style": "dash"
+  },
+  "MD007": {
+    "indent": 4
+  },
+  "MD013": false,
+  "MD014": false,
+  "MD022": false,
+  "MD029": {
+    "style": "ordered"
+  },
+  "MD033": {
+    "allowed_elements": ["a"]
+  }
+}

CONTRIBUTING.md

@@ -10,11 +10,14 @@ Before submitting an issue or a pull request, please search the repository for e
 
 ## Submitting a pull request
 
-0. Fork and clone the repository.
-0. Create a new branch: `git switch -c my-branch-name`.
-0. Make your change, add tests, and make sure the tests still pass.
-0. Push to your fork and submit a pull request.
-0. Pat yourself on the back and wait for your pull request to be reviewed and merged.
+1. Fork and clone the repository.
+2. Create a new branch: `git switch -c my-branch-name`.
+3. Make your change, add tests, and make sure the tests still pass.
+4. Run `make docs-lint` to check if the documentation is up to date.
+5. Update the documentation templates if needed.
+6. Run `make docs-generate` to generate changes to the documentation.
+7. Push to your fork and submit a pull request.
+8. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
@@ -33,26 +36,31 @@ This section describes a typical sequence performed when developing locally. Ful
 Once you have the repository cloned, there's a couple of additional steps you'll need to take. Since most of the testing is acceptance or integration testing, we need to manipulate real GitHub resources in order to run it. Useful setup steps are listed below:
 
 - If you haven't already, [create a GitHub organization you can use for testing](#github-organization).
-  - Optional: you may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account.
-  - Your organization _must_ have a repository called `terraform-template-module`. The [terraformtesting/terraform-template-module](https://github.com/terraformtesting/terraform-template-module) repo is a good, re-usable example.
-    - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo.
+    - Optional: you may find it beneficial to create a test user as well in order to avoid potential rate-limiting issues on your main account.
+    - Your organization _must_ have a repository called `terraform-template-module`. The [terraformtesting/terraform-template-module](https://github.com/terraformtesting/terraform-template-module) repo is a good, re-usable example.
+        - You _must_ make sure that the "Template Repository" item in Settings is checked for this repo.
 - If you haven't already, generate a Personal Access Token (PAT) for authenticating your test runs.
 - Export the necessary configuration for authenticating your provider with GitHub
+
   ```sh
   export GITHUB_TOKEN=<token of a user with an organization account>
   export GITHUB_ORGANIZATION=<name of an organization>
   ```
+
 - Build the project with `make build`
 - Try an example test run from the default (`main`) branch, like `TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubRepositories`. All those tests should pass.
 
 ### Local Development Iteration
 
 1. Write a test describing what you will fix. See [`github_label`](./github/resource_github_issue_label_test.go) for an example format.
-1. Run your test and observe it fail. Enabling debug output allows for observing the underlying requests and responses made as well as viewing state (search `STATE:`) generated during the acceptance test run.
+2. Run your test and observe it fail. Enabling debug output allows for observing the underlying requests and responses made as well as viewing state (search `STATE:`) generated during the acceptance test run.
+
 ```sh
 TF_LOG=DEBUG TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel
 ```
+
 1. Align the resource's implementation to your test case and observe it pass:
+
 ```sh
 TF_ACC=1 go test -v ./... -run ^TestAccGithubIssueLabel
 ```
@@ -67,27 +75,29 @@ Println debugging can easily be used to obtain information about how code change
 
 If a full debugger is desired, VSCode may be used. In order to do so,
 
-0. Create a launch.json file with this configuration:
+1. Create a launch.json file with this configuration:
+
 ```json
 {
-	"name": "Attach to Process",
-	"type": "go",
-	"request": "attach",
-	"mode": "local",
-	"processId": 0,
+ "name": "Attach to Process",
+ "type": "go",
+ "request": "attach",
+ "mode": "local",
+ "processId": 0,
 }
 ```
+
 Setting a `processId` of 0 allows a dropdown to select the process of the provider.
 
-0. Add a sleep call (e.g. `time.Sleep(10 * time.Second)`) in the [`func providerConfigure(p *schema.Provider) schema.ConfigureFunc`](https://github.com/integrations/terraform-provider-github/blob/cec7e175c50bb091feecdc96ba117067c35ee351/github/provider.go#L274C1-L274C64) before the immediate `return` call. This will allow time to connect the debugger while the provider is initializing, before any critical logic happens.
+1. Add a sleep call (e.g. `time.Sleep(10 * time.Second)`) in the [`func providerConfigure(p *schema.Provider) schema.ConfigureFunc`](https://github.com/integrations/terraform-provider-github/blob/cec7e175c50bb091feecdc96ba117067c35ee351/github/provider.go#L274C1-L274C64) before the immediate `return` call. This will allow time to connect the debugger while the provider is initializing, before any critical logic happens.
 
-0. Build the terraform provider with debug flags enabled and copy it to the appropriate bin folder with a command like `go build -gcflags="all=-N -l" -o ~/go/bin/`.
+2. Build the terraform provider with debug flags enabled and copy it to the appropriate bin folder with a command like `go build -gcflags="all=-N -l" -o ~/go/bin/`.
 
-0. Create or edit a `dev.tfrc` that points toward the newly-built binary, and export the `TF_CLI_CONFIG_FILE` variable to point to it. Further instructions on this process may be found in the [Building the provider](#using-a-local-version-of-the-provider) section.
+3. Create or edit a `dev.tfrc` that points toward the newly-built binary, and export the `TF_CLI_CONFIG_FILE` variable to point to it. Further instructions on this process may be found in the [Building the provider](#using-a-local-version-of-the-provider) section.
 
-0. Run a terraform command (e.g. `terraform apply`). While the provider pauses on initialization, go to VSCode and click "Attach to Process". In the search box that appears, type `terraform-provi` and select the terraform provider process.
+4. Run a terraform command (e.g. `terraform apply`). While the provider pauses on initialization, go to VSCode and click "Attach to Process". In the search box that appears, type `terraform-provi` and select the terraform provider process.
 
-0. The debugger is now connected! During a typical terraform command, the plugin will be invoked multiple times. If the debugger disconnects and the plugin is invoked again later in the run, the developer will have to re-attach each time as the process ID changes.
+5. The debugger is now connected! During a typical terraform command, the plugin will be invoked multiple times. If the debugger disconnects and the plugin is invoked again later in the run, the developer will have to re-attach each time as the process ID changes.
 
 
 ## Manual Testing
@@ -121,7 +131,7 @@ provider_installation {
 }
 ```
 
-See https://www.terraform.io/docs/cli/config/config-file.html for more details.
+See [Terraform CLI Config File](https://www.terraform.io/docs/cli/config/config-file.html) for more details.
 
 When running examples, you should spot the following warning to confirm you are using a local build:
 
@@ -179,45 +189,45 @@ This may come in handy when debugging both acceptance and manual testing.
 
 ```json
 {
-	// for information on how to debug the provider, see the CONTRIBUTING.md file
-	"version": "0.2.0",
-	"configurations": [
-		{
-			"name": "Launch test function",
-			"type": "go",
-			"request": "launch",
-			"mode": "test",
-			// note that the program file must be in the same package as the test to run,
-			// though it does not necessarily have to be the file that contains the test.
-			"program": "/home/kfcampbell/github/dev/terraform-provider-github/github/resource_github_team_members_test.go",
-			"args": [
-				"-test.v",
-				"-test.run",
-				"^TestAccGithubRepositoryTopics$" // ^ExactMatch$
-			],
-			"env": {
-				"GITHUB_TEST_COLLABORATOR": "kfcampbell-terraform-test-user",
-				"GITHUB_TEST_COLLABORATOR_TOKEN": "ghp_xxx",
-				"GITHUB_TEST_USER": "kfcampbell",
-				"GITHUB_TOKEN": "ghp_xxx",
-				"GITHUB_TEMPLATE_REPOSITORY": "terraform-template-module",
-				"GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID": "12345678",
-				// "GITHUB_OWNER": "kfcampbell-terraform-provider",
-				// "GITHUB_OWNER": "kfcampbell",
-				"GITHUB_ORGANIZATION": "kfcampbell-terraform-provider", // GITHUB_ORGANIZATION is required for organization integration tests
-				"TF_CLI_CONFIG_FILE": "/home/kfcampbell/github/dev/terraform-provider-github/examples/dev.tfrc",
-				"TF_ACC": "1",
-				"TF_LOG": "DEBUG",
-				"APP_INSTALLATION_ID": "12345678"
-			}
-		},
-		{
-			"name": "Attach to Process",
-			"type": "go",
-			"request": "attach",
-			"mode": "local",
-			"processId": 0
-		}
-	]
+ // for information on how to debug the provider, see the CONTRIBUTING.md file
+ "version": "0.2.0",
+ "configurations": [
+  {
+   "name": "Launch test function",
+   "type": "go",
+   "request": "launch",
+   "mode": "test",
+   // note that the program file must be in the same package as the test to run,
+   // though it does not necessarily have to be the file that contains the test.
+   "program": "/home/kfcampbell/github/dev/terraform-provider-github/github/resource_github_team_members_test.go",
+   "args": [
+    "-test.v",
+    "-test.run",
+    "^TestAccGithubRepositoryTopics$" // ^ExactMatch$
+   ],
+   "env": {
+    "GITHUB_TEST_COLLABORATOR": "kfcampbell-terraform-test-user",
+    "GITHUB_TEST_COLLABORATOR_TOKEN": "ghp_xxx",
+    "GITHUB_TEST_USER": "kfcampbell",
+    "GITHUB_TOKEN": "ghp_xxx",
+    "GITHUB_TEMPLATE_REPOSITORY": "terraform-template-module",
+    "GITHUB_TEMPLATE_REPOSITORY_RELEASE_ID": "12345678",
+    // "GITHUB_OWNER": "kfcampbell-terraform-provider",
+    // "GITHUB_OWNER": "kfcampbell",
+    "GITHUB_ORGANIZATION": "kfcampbell-terraform-provider", // GITHUB_ORGANIZATION is required for organization integration tests
+    "TF_CLI_CONFIG_FILE": "/home/kfcampbell/github/dev/terraform-provider-github/examples/dev.tfrc",
+    "TF_ACC": "1",
+    "TF_LOG": "DEBUG",
+    "APP_INSTALLATION_ID": "12345678"
+   }
+  },
+  {
+   "name": "Attach to Process",
+   "type": "go",
+   "request": "attach",
+   "mode": "local",
+   "processId": 0
+  }
+ ]
 }
 ```

GNUmakefile

@@ -1,12 +1,12 @@
 TEST?=$$(go list ./... |grep -v 'vendor')
-WEBSITE_REPO=github.com/hashicorp/terraform-website
 PKG_NAME=github
 
 default: build
 
 tools:
-	go install github.com/client9/misspell/cmd/[email protected]
-	go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
+	go install github.com/golangci/misspell/cmd/misspell@latest
+	go install github.com/golangci/golangci-lint/v2/cmd/[email protected]
+	go install github.com/hashicorp/terraform-plugin-docs/cmd/[email protected]
 
 build: fmtcheck
 	CGO_ENABLED=0 go build -ldflags="-s -w" ./...
@@ -37,22 +37,14 @@ test-compile:
 	fi
 	CGO_ENABLED=0 go test -c $(TEST) $(TESTARGS)
 
-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-lint:
-	@echo "==> Checking website against linters..."
-	@misspell -error -source=text website/
-
-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) $(GOPATH)/src/$(WEBSITE_REPO)
-endif
-	@$(MAKE) -C $(GOPATH)/src/$(WEBSITE_REPO) website-provider-test PROVIDER_PATH=$(shell pwd) PROVIDER_NAME=$(PKG_NAME)
-
-.PHONY: build test testacc fmt fmtcheck lint tools test-compile website website-lint website-test
+docs-generate:
+	@echo "==> Generating docs..."
+	tfplugindocs generate
+
+docs-lint:
+	@echo "==> Checking docs against linters..."
+	@misspell -error -source=text docs/
+	@tfplugindocs validate
+
+
+.PHONY: build test testacc fmt fmtcheck lint tools test-compile docs-generate docs-lint

docs/data-sources/actions_environment_public_key.md

@@ -0,0 +1,32 @@
+---
+page_title: "github_actions_environment_public_key Data Source - terraform-provider-github"
+description: |-
+  Get information on a GitHub Actions Environment Public Key.
+---
+
+# github_actions_environment_public_key (Data Source)
+
+Use this data source to retrieve information about a GitHub Actions public key of a specific environment. This data source is required to be used with other GitHub secrets interactions. Note that the provider `token` must have admin rights to a repository to retrieve the action public keys of it's environments.
+
+## Example Usage
+
+```terraform
+data "github_actions_environment_public_key" "example" {
+  repository = "example_repo"
+  environment = "example_environment"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `environment` (String) Name of the environment to get public key from.
+- `repository` (String) Name of the repository to get public key from.
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `key` (String) Actual key retrieved.
+- `key_id` (String) ID of the key that has been retrieved.

docs/data-sources/actions_environment_secrets.md

@@ -0,0 +1,27 @@
+---
+page_title: "github_actions_environment_secrets Data Source - terraform-provider-github
+description: |-
+  Get Actions secrets of the repository environment
+---
+
+# github_actions_environment_secrets (Data Source)
+
+Use this data source to retrieve the list of secrets of the repository environment.
+
+## Example Usage
+
+```terraform
+data "github_actions_environment_secrets" "example" {
+    name        = "exampleRepo"
+    environment = "exampleEnvironment"
+}
+```
+
+## Argument Reference
+
+## Attributes Reference
+
+- `secrets` - list of secrets for the environment
+    - `name` - Name of the secret
+    - `created_at` - Timestamp of the secret creation
+    - `updated_at` - Timestamp of the secret last update

docs/data-sources/actions_environment_variables.md

@@ -0,0 +1,28 @@
+---
+page_title: "github_actions_environment_variables Data Source - terraform-provider-github
+description: |-
+  Get Actions variables of the repository environment
+---
+
+# github_actions_environment_variables (Data Source)
+
+Use this data source to retrieve the list of variables of the repository environment.
+
+## Example Usage
+
+```terraform
+data "github_actions_environment_variables" "example" {
+    name        = "exampleRepo"
+    environment = "exampleEnvironment"
+}
+```
+
+## Argument Reference
+
+## Attributes Reference
+
+- `variables` - list of variables for the environment
+    - `name` - Name of the variable
+    - `value` - Value of the variable
+    - `created_at` - Timestamp of the variable creation
+    - `updated_at` - Timestamp of the variable last update

docs/data-sources/actions_organization_oidc_subject_claim_customization_template.md

@@ -0,0 +1,24 @@
+---
+page_title: "github_actions_organization_oidc_subject_claim_customization_template Data Source - terraform-provider-github
+description: |-
+  Get a GitHub Actions organization OpenID Connect customization template
+---
+
+# github_actions_organization_oidc_subject_claim_customization_template (Data Source)
+
+Use this data source to retrieve the OpenID Connect subject claim customization template for an organization
+
+## Example Usage
+
+```terraform
+data "github_actions_organization_oidc_subject_claim_customization_template" "example" {
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `include_claim_keys` (List of String) The list of OpenID Connect claim keys