Merge pull request #280 from lornest/master

Terraform Provider Documentation Alignment

.github/workflows/tfplugindocs-check.yml

@@ -0,0 +1,36 @@
+name: tfplugindocs check
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  tfplugindocs_check:
+    name: tfplugindocs check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+      - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
+        with:
+          go-version-file: tools/go.mod
+      - name: GOCACHE
+        run: |
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_ENV
+      - uses: actions/cache@3624ceb22c1c5a301c8db4169662070a689d9ea8 # v4.1.1
+        continue-on-error: true
+        timeout-minutes: 2
+        with:
+          path: ${{ env.GOCACHE }}
+          key: ${{ runner.os }}-GOCACHE-${{ hashFiles('go.sum') }}-${{ hashFiles('internal/**') }}
+      - uses: actions/cache@3624ceb22c1c5a301c8db4169662070a689d9ea8 # v4.1.1
+        continue-on-error: true
+        timeout-minutes: 2
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-pkg-mod-${{ hashFiles('go.sum') }}
+      - run: |
+          make tools
+          make docs
+          git add -N docs/
+          git diff --exit-code

.github/workflows/tfplugindocs-generate.yml

@@ -0,0 +1,48 @@
+name: tfplugindocs generate
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/tfplugindocs-check.yml
+      - Makefile
+      - docs/**
+      - examples/**
+      - templates/**
+      - sonarqube/**
+
+jobs:
+  tfplugindocs_generate:
+    name: tfplugindocs generate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@eef61447b9ff4aafe5dcd4e0bbf5d482be7e7871 # v4.2.1
+        with:
+          persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal token
+          fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+      - uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
+        with:
+          go-version-file: tools/go.mod
+      - name: GOCACHE
+        run: |
+          echo "GOCACHE=$(go env GOCACHE)" >> $GITHUB_ENV
+      - uses: actions/cache@3624ceb22c1c5a301c8db4169662070a689d9ea8 # v4.1.1
+        continue-on-error: true
+        timeout-minutes: 2
+        with:
+          path: ${{ env.GOCACHE }}
+          key: ${{ runner.os }}-GOCACHE-${{ hashFiles('go.sum') }}-${{ hashFiles('internal/**') }}
+      - uses: actions/cache@3624ceb22c1c5a301c8db4169662070a689d9ea8 # v4.1.1
+        continue-on-error: true
+        timeout-minutes: 2
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-pkg-mod-${{ hashFiles('go.sum') }}
+      - run: |
+          make tools
+          make docs
+      - uses: actions-js/push@5a7cbd780d82c0c937b5977586e641b2fd94acc5 #v1.5
+        name: Github commit and push
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.head_ref }}
+          message: "[bot] docs: tfplugindocs generate"

.gitignore

@@ -27,3 +27,6 @@ coverage.txt
 # dist directory for local testingg
 dist/
 .vscode/settings.json
+
+.DS_Store
+

Makefile

@@ -3,11 +3,18 @@ export TF_LOG=DEBUG
 SRC=$(shell find . -name '*.go')
 SONARQUBE_IMAGE?=sonarqube:latest
 SONARQUBE_START_SLEEP?=60
+GO_VER ?= go
 
-.PHONY: all vet build test
+.PHONY: all vet build test tools docs
 
 all: fmt vet build
 
+tools:
+	cd tools && $(GO_VER) install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
+
+docs:
+	@tfplugindocs generate
+
 build:
 	go build -a -tags netgo -o terraform-provider-sonarqube
 

README.md

@@ -11,15 +11,16 @@ Terraform provider for managing Sonarqube configuration
 This is a community provider and is not supported by Hashicorp.
 
 ## Installation
+
 This provider has been published to the Terraform Registry at https://registry.terraform.io/providers/jdamata/sonarqube. Please visit the registry for documentation and installation instructions.
 
 ## Developing the Provider
 
 Working on this provider requires the following:
 
-* [Terraform](https://www.terraform.io/downloads.html)
-* [Go](http://www.golang.org)
-* [Docker Engine](https://docs.docker.com/engine/install/)
+- [Terraform](https://www.terraform.io/downloads.html)
+- [Go](http://www.golang.org)
+- [Docker Engine](https://docs.docker.com/engine/install/)
 
 You will also need to correctly setup a [GOPATH](http://golang.org/doc/code.html#GOPATH), as well as adding `${GOPATH}/bin` to your `$PATH`.
 
@@ -31,6 +32,17 @@ In order to run the full suite of Acceptance tests, run `make -i testacc`. These
 $ make -i testacc
 ```
 
+## Generate documentation
+
+Documentation is generated using `tfplugindocs`. These are auto-generated when creating a PR to the project. 
+
+If you wish to generate documentation locally to verify it's accuracy, run the following commands:
+
+```sh
+$ make tools
+$ make docs
+```
+
 ## Debugging the Provider
 
-See [debugging.md](docs/debugging.md)
+See [debugging.md](debugging.md)

docs/debugging.md → debugging.md

@@ -7,6 +7,7 @@ You can debug the provider using a tool similar to [delve](https://github.com/go
 ### Visual Studio Code
 
 Using [Visual Studio Code](https://code.visualstudio.com/) with the [Go extension](https://marketplace.visualstudio.com/items?itemName=golang.go) installed, you would add a configuration similar to this to your `launch.json` file:
+
 ```json
 {
     "name": "Debug Terraform Provider",
@@ -23,7 +24,9 @@ Using [Visual Studio Code](https://code.visualstudio.com/) with the [Go extensio
     "showLog": true
 }
 ```
+
 Start the process using this configuration and then follow the instructions provided in the debug console:
+
 ```shell
 Provider started. To attach Terraform CLI, set the TF_REATTACH_PROVIDERS environment variable with the following:
 
@@ -35,6 +38,7 @@ Provider started. To attach Terraform CLI, set the TF_REATTACH_PROVIDERS environ
 ### Delve CLI
 
 With the delve CLI you would start a delve debugging session:
+
 ```shell
 dlv exec --accept-multiclient --continue --headless ./terraform-provider-example -- -debug
 ```

docs/data-sources/group.md

@@ -0,0 +1,31 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_group Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube Group resource
+---
+
+# sonarqube_group (Data Source)
+
+Use this data source to get a Sonarqube Group resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_group" "group" {
+  name = "terraform-test"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of the group.
+
+### Read-Only
+
+- `description` (String) The group description.
+- `id` (String) The ID of this resource.

docs/data-sources/portfolio.md

@@ -0,0 +1,38 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_portfolio Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube portfolio resource
+---
+
+# sonarqube_portfolio (Data Source)
+
+Use this data source to get a Sonarqube portfolio resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_portfolio" "portfolio" {
+  key = "portfolio-key"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `key` (String) The key of the portfolio
+
+### Read-Only
+
+- `branch` (String) Which branch is analyzed
+- `description` (String) Description of the portfolio
+- `id` (String) The ID of this resource.
+- `name` (String) Name of the portfolio
+- `qualifier` (String) `VW` (portfolios always have this qualifier)
+- `regexp` (String) The regular expression used to populate the portfolio. Only active when `selection_mode` is `REGEXP`
+- `selection_mode` (String) How the Portfolio is populated. Possible values are `NONE`, `MANUAL`, `TAGS`, `REGEXP` or `REST`. [See docs](https://docs.sonarqube.org/9.8/project-administration/managing-portfolios/#populating-portfolios) for how Portfolio population works
+- `tags` (List of String) The list of tags used to populate the Portfolio. Only active when `selection_mode` is `TAGS`
+- `visibility` (String) Portfolio visibility

docs/data-sources/project.md

@@ -0,0 +1,32 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_project Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube project resource
+---
+
+# sonarqube_project (Data Source)
+
+Use this data source to get a Sonarqube project resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_project" "project" {
+  project = "projet-key-id"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `project` (String) The project key of the project
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `name` (String) Name of the project
+- `visibility` (String) Project visibility

docs/data-sources/qualitygate.md

@@ -0,0 +1,43 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_qualitygate Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube qualitygate resource
+---
+
+# sonarqube_qualitygate (Data Source)
+
+Use this data source to get a Sonarqube qualitygate resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_qualitygate" "main" {
+  name = "example"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of the Quality Gate.
+
+### Read-Only
+
+- `condition` (List of Object) List of Quality Gate conditions. (see [below for nested schema](#nestedatt--condition))
+- `copy_from` (String) Origin of the Quality Gate
+- `id` (String) The ID of this resource.
+- `is_default` (Boolean) Quality Gate default.
+
+<a id="nestedatt--condition"></a>
+### Nested Schema for `condition`
+
+Read-Only:
+
+- `id` (String)
+- `metric` (String)
+- `op` (String)
+- `threshold` (String)

docs/data-sources/qualityprofile.md

@@ -0,0 +1,33 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_qualityprofile Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube qualityprofile resource
+---
+
+# sonarqube_qualityprofile (Data Source)
+
+Use this data source to get a Sonarqube qualityprofile resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_qualityprofile" "main" {
+  name = "example"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `name` (String) The name of the Quality Profile
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `is_default` (Boolean) Quality Profile default
+- `key` (String) The key of the Quality Profile
+- `language` (String) Quality Profile language

docs/data-sources/rule.md

@@ -0,0 +1,36 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "sonarqube_rule Data Source - terraform-provider-sonarqube"
+subcategory: ""
+description: |-
+  Use this data source to get a Sonarqube rule resource
+---
+
+# sonarqube_rule (Data Source)
+
+Use this data source to get a Sonarqube rule resource
+
+## Example Usage
+
+```terraform
+data "sonarqube_rule" "rule" {
+  key = "squid:forbidSonar"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `key` (String) The key of the sonarqube rule. Should be <repo>:<name>. https://next.sonarqube.com/sonarqube/web_api/api/rules?query=api%2Frules%2Fcreate
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
+- `markdown_description` (String) Rule description
+- `name` (String) Rule name
+- `severity` (String) Rule severity
+- `status` (String) Rule status
+- `template_key` (String) Key of the template rule
+- `type` (String) Rule type