feat: Generate docs

.github/pull_request_template.md

@@ -7,12 +7,12 @@ Resolves #ISSUE_NUMBER
 ### Before the change?
 <!-- Please describe the current behavior that you are modifying. -->
 
-- 
+-
 
 ### After the change?
 <!-- Please describe the behavior or changes that are being added by this PR. -->
 
-- 
+-
 
 ### Pull request checklist
 

.github/workflows/ci.yaml

@@ -33,8 +33,25 @@ jobs:
         with:
           go-version-file: go.mod
           cache: true
+      - name: Set-up Terraform
+        uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd # v3.1.2
+        with:
+          terraform_version: latest
+          terraform_wrapper: false
+      - name: Set-up rumdl
+        uses: action-stars/install-tool-from-github-release@1fa61c3bea52eca3bcdb1f5c961a3b113fe7fa54 # v0.2.6
+        with:
+          github_token: ${{ github.token }}
+          owner: rvben
+          repository: rumdl
+          filename_format: "{name}-v{version}-{arch}-{os}.{ext}"
+          arch_amd64: x86_64
+          os_linux: unknown-linux-gnu
+          check_command: rumdl --version
+          version: latest
       - run: make tools
       - run: make lintcheck
-      - run: make website-lint
       - run: make build
       - run: make test
+      - run: make checkdocs
+      - run: make lintdocs RUMDL_ARGS="--output-format github"

.golangci.yml

@@ -1,6 +1,4 @@
 version: "2"
-run:
-  modules-download-mode: vendor
 
 linters:
   default: none

.rumdl.toml

@@ -0,0 +1,15 @@
+[global]
+disable = ["MD013", "MD028"]
+
+[per-file-ignores]
+".github/pull_request_template.md" = ["MD041"]
+"docs/**/*.md" = ["MD059"]
+
+[MD024]
+siblings-only = true
+
+[MD033]
+allowed-elements = ["a", "br", "details", "img", "summary", "sub", "sup"]
+
+[MD052]
+shortcut-syntax = true

CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ a project may be further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at opensource@github.com. All
+reported by contacting the project team at <opensource@github.com>. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.
@@ -68,9 +68,9 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

CONTRIBUTING.md

@@ -13,8 +13,9 @@ Before submitting an issue or a pull request, please search the repository for e
 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. Push to your fork and submit a pull request.
-5. Pat yourself on the back and wait for your pull request to be reviewed and merged.
+4. Make sure the documentation has been updated, and run `make generatedocs`.
+5. Push to your fork and submit a pull request.
+6. 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:
 

GNUmakefile

@@ -1,10 +1,11 @@
 SWEEP?=repositories,teams
 PKG_NAME=github
 TEST?=./$(PKG_NAME)/...
-WEBSITE_REPO=github.com/hashicorp/terraform-website
 
 COVERAGEARGS?=-race -coverprofile=coverage.txt -covermode=atomic
 
+RUMDL_ARGS?=--output-format text
+
 # VARIABLE REFERENCE:
 #
 # Test-specific variables:
@@ -28,7 +29,6 @@ endif
 default: build
 
 tools:
-	go install github.com/client9/misspell/cmd/misspell@v0.3.4
 	go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.6.0
 
 build: lintcheck
@@ -66,22 +66,21 @@ sweep:
 	@echo "WARNING: This will destroy infrastructure. Use only in development accounts."
 	go test $(TEST) -v -sweep=$(SWEEP) $(SWEEPARGS)
 
-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)
+generatedocs:
+	@go generate ./...
 
-website-lint:
-	@echo "==> Checking website against linters..."
-	@misspell -error -source=text website/
+fmtdocs:
+	@rumdl fmt --fix .
 
-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)
+lintdocs:
+	@rumdl check $(RUMDL_ARGS) .
+	@go tool tfplugindocs validate
+
+checkdocs: generatedocs
+	@git diff --quiet ||\
+		{ echo "New file modification detected in the Git working tree. Please check in before commit."; git --no-pager diff --name-only | uniq | awk '{print "  - " $$0}'; \
+		if [ "${CI}" = true ]; then\
+			exit 1;\
+		fi;}
 
-.PHONY: build test testacc fmt lint lintcheck tools website website-lint website-test sweep
+.PHONY: tools build fmt lint lintcheck test testacc sweep generatedocs fmtdocs lintdocs checkdocs

README.md

@@ -1,24 +1,21 @@
-Terraform Provider GitHub
-=========================
+# Terraform Provider GitHub
 
-<img src="https://cloud.githubusercontent.com/assets/98681/24211275/c4ebd04e-0ee8-11e7-8606-061d656a42df.png" width="72" height="">
+|<img src="https://cloud.githubusercontent.com/assets/98681/24211275/c4ebd04e-0ee8-11e7-8606-061d656a42df.png" width="72" height=""> | <img src="https://raw.githubusercontent.com/hashicorp/terraform-website/d841a1e5fca574416b5ca24306f85a0f4f41b36d/content/source/assets/images/logo-terraform-main.svg" width="300px">|
 
-<img src="https://raw.githubusercontent.com/hashicorp/terraform-website/d841a1e5fca574416b5ca24306f85a0f4f41b36d/content/source/assets/images/logo-terraform-main.svg" width="300px">
-
-This project is used to manipulate GitHub resources (repositories, teams, files, etc.) using Terraform. Its Terraform Registry page can be found [here](https://registry.terraform.io/providers/integrations/github/).
+This project is used to manipulate GitHub resources (repositories, teams, files, etc.) using Terraform; it can be found in the [Terraform Registry](https://registry.terraform.io/providers/integrations/github).
 
 ## Requirements
 
--	[Terraform](https://www.terraform.io/downloads.html) 0.10.x
--	[Go](https://golang.org/doc/install) 1.24.x (to build the provider plugin)
+- [Terraform](https://www.terraform.io/downloads.html) 1.x
+- [Go](https://golang.org/doc/install) 1.24.x (to build the provider plugin)
 
 ## Usage
 
-Detailed documentation for the GitHub provider can be found [here](https://registry.terraform.io/providers/integrations/github).
+Detailed documentation for the GitHub provider can be found in the [Terraform Registry](https://registry.terraform.io/providers/integrations/github).
 
 ## Contributing
 
-Detailed documentation for contributing to the GitHub provider can be found [here](CONTRIBUTING.md).
+Detailed documentation for contributing to the GitHub provider can be found in the [contributing guide](CONTRIBUTING.md).
 
 ## Roadmap
 

RELEASE.md

@@ -1,4 +1,4 @@
-## Release Flow
+# Release Flow
 
 The release process uses GitHub Actions and [`goreleaser`](https://github.com/goreleaser/goreleaser) to build, sign, and upload provider binaries to a GitHub release. Release are triggered by a tag with the pattern `v*` (e.g. `v1.2.3`); these tags may only be created from the default branch (`main`) or branches that match the pattern `release-v*`.
 

SECURITY.md

@@ -1,3 +1,5 @@
+# Security Policy
+
 If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
 
 Thanks for helping make this project safe for everyone.

docs.go

@@ -0,0 +1,10 @@
+package main
+
+// Format Terraform code for use in documentation.
+//go:generate terraform fmt -recursive examples/
+
+// Generate documentation.
+//go:generate go tool github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs generate --rendered-provider-name=GitHub
+
+// Check for misspellings in documentation.
+//go:generate go tool github.com/client9/misspell/cmd/misspell -error -i "docs/**/*.md"

docs/data-sources/actions_environment_public_key.md

@@ -0,0 +1,28 @@
+---
+page_title: "github_actions_environment_public_key (Data Source) - 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"
+}
+```
+
+## Argument Reference
+
+- `repository` - (Required) Name of the repository to get public key from.
+- `environment` - (Required) Name of the environment to get public key from.
+
+## Attributes Reference
+
+- `key_id` - ID of the key that has been retrieved.
+- `key` - Actual key retrieved.

docs/data-sources/actions_environment_secrets.md

@@ -0,0 +1,27 @@
+---
+page_title: "github_actions_environment_secrets (Data Source) - GitHub"
+description: |-
+  Get Actions secrets of the repository environment
+---
+
+# github\_actions\_environment\_secrets
+
+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) - GitHub"
+description: |-
+  Get Actions variables of the repository environment
+---
+
+# github\_actions\_environment\_variables
+
+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,22 @@
+---
+page_title: "github_actions_organization_oidc_subject_claim_customization_template (Data Source) - GitHub"
+description: |-
+  Get a GitHub Actions organization OpenID Connect customization template
+---
+
+# actions_organization_oidc_subject_claim_customization_template
+
+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" {
+}
+```
+
+## Argument Reference
+
+## Attributes Reference
+
+- `include_claim_keys` - The list of OpenID Connect claim keys.

docs/data-sources/actions_organization_public_key.md

@@ -0,0 +1,20 @@
+---
+page_title: "github_actions_organization_public_key (Data Source) - GitHub"
+description: |-
+  Get information on a GitHub Actions Organization Public Key.
+---
+
+# github_actions_organization_public_key (Data Source)
+
+Use this data source to retrieve information about a GitHub Actions Organization public key. This data source is required to be used with other GitHub secrets interactions. Note that the provider `token` must have admin rights to an organization to retrieve it's action public key.
+
+## Example Usage
+
+```terraform
+data "github_actions_organization_public_key" "example" {}
+```
+
+## Attributes Reference
+
+- `key_id` - ID of the key that has been retrieved.
+- `key` - Actual key retrieved.

docs/data-sources/actions_organization_registration_token.md

@@ -0,0 +1,23 @@
+---
+page_title: "github_actions_organization_registration_token (Data Source) - GitHub"
+description: |-
+  Get a GitHub Actions organization registration token.
+---
+
+# actions_registration_token
+
+Use this data source to retrieve a GitHub Actions organization registration token. This token can then be used to register a self-hosted runner.
+
+## Example Usage
+
+```terraform
+data "github_actions_organization_registration_token" "example" {
+}
+```
+
+## Argument Reference
+
+## Attributes Reference
+
+- `token` - The token that has been retrieved.
+- `expires_at` - The token expiration date.

docs/data-sources/actions_organization_secrets.md

@@ -0,0 +1,26 @@
+---
+page_title: "github_actions_organization_secrets (Data Source) - GitHub"
+description: |-
+  Get actions secrets of the organization
+---
+
+# github\_actions\_organization\_secrets
+
+Use this data source to retrieve the list of secrets of the organization.
+
+## Example Usage
+
+```terraform
+data "github_actions_organization_secrets" "example" {
+}
+```
+
+## Argument Reference
+
+## Attributes Reference
+
+- `secrets` - list of secrets for the repository
+  - `name` - Secret name
+  - `visibility` - Secret visibility
+  - `created_at` - Timestamp of the secret creation
+  - `updated_at` - Timestamp of the secret last update