SCALRCORE-24642 Provider > Autogenerate documentation (#277)

* SCALRCORE-24642 Add terraform-plugin-docs dependency and generate cmd

* SCALRCORE-24642 Bump Go version to 1.19

* SCALRCORE-24642 Implement docs generation

* SCALRCORE-24642 Improve templates, add tools for formatting and page ordering

* SCALRCORE-24642 Add Github workflows for documentation publishing

* SCALRCORE-24642 Generate docs

.github/workflows/default.yml

@@ -3,7 +3,6 @@ name: default
 on:
   push:
     paths-ignore:
-      - docs/**
       - CHANGELOG.md
       - CONTRIBUTING.md
       - README.md
@@ -16,12 +15,33 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v3
         with:
           version: v1.48.0
           args: --timeout 2m
+      - name: Generate
+        run: go generate
+      - name: Validate generated code
+        shell: bash
+        run: |
+          if [ -z "$(git status --porcelain)" ]; then
+            echo "ok";
+          else
+            echo "*** Unexpected differences after code generation. Run 'go generate' and commit.";
+            exit 1;
+          fi
+
+  docs-preview:
+    name: 'Docs: preview'
+    needs: [lint]
+    uses: ./.github/workflows/rdme.yml
+    with:
+      version: '0.0.4'
+      dry: true
+    secrets:
+      README_API_KEY: ${{ secrets.README_API_KEY }}
 
   unit-tests:
     name: unit-tests
@@ -30,7 +50,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: Run unit tests
         run: make test
 
@@ -51,7 +71,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: Set API_BRANCH
         run: echo "API_BRANCH=${GITHUB_REF#refs/heads/}" >> $GITHUB_ENV
       - name: Check if same branch exists in fatmouse repository
@@ -209,7 +229,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v3
         with:
@@ -256,7 +276,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v3
         with:
@@ -278,3 +298,13 @@ jobs:
           gcs-bucket: ${{ secrets.BUCKET_NAME }}
           registry-domain: ${{ secrets.DOMAIN }}
           dry-run: false
+
+  docs-publish:
+    name: 'Docs: publish'
+    needs: [ release ]
+    uses: ./.github/workflows/rdme.yml
+    with:
+      version: '0.0.4'
+      dry: false
+    secrets:
+      README_API_KEY: ${{ secrets.README_API_KEY }}

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: '🚀 Publish the documentation'
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Readme documentation version'
+        required: true
+        type: string
+        default: '0.0.4'
+      dry:
+        description: 'Perform a dry run (preview the changes without publishing)'
+        required: true
+        type: boolean
+        default: true
+
+jobs:
+  docs:
+    name: Docs
+    uses: ./.github/workflows/rdme.yml
+    with:
+      version: ${{ inputs.version }}
+      dry: ${{ inputs.dry }}
+    secrets:
+      README_API_KEY: ${{ secrets.README_API_KEY }}

.github/workflows/rdme.yml

@@ -0,0 +1,33 @@
+name: '(callee) readme.io'
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'Readme documentation version'
+        required: true
+        type: string
+      dry:
+        description: 'Perform a dry run (preview the changes without publishing)'
+        required: true
+        type: boolean
+    secrets:
+      README_API_KEY:
+        required: true
+
+jobs:
+  readme:
+    name: readme.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Preview
+        if: inputs.dry == true
+        uses: readmeio/rdme@v8
+        with:
+          rdme: docs ./docs --key=${{ secrets.README_API_KEY }} --version=${{ inputs.version }} --dryRun
+      - name: Publish
+        if: inputs.dry == false
+        uses: readmeio/rdme@v8
+        with:
+          rdme: docs ./docs --key=${{ secrets.README_API_KEY }} --version=${{ inputs.version }}

.github/workflows/upstream.yml

@@ -49,7 +49,7 @@ jobs:
         run: make notify-upstream upstream_sha=${{ github.event.inputs.upstream-sha }} state=pending run_id=${{ github.run_id }}
       - uses: actions/setup-go@v3
         with:
-          go-version: "1.18"
+          go-version: "1.19"
       - name: Clone fatmouse repo
         uses: actions/checkout@v3
         with:

.go-version

@@ -1 +1 @@
-1.18.9
+1.19.13

CONTRIBUTING.md

@@ -23,9 +23,15 @@ The main steps to follow when adding a resource are:
 - implement resource structs and CRUD methods in [Scalr Go Client](https://github.com/Scalr/go-scalr/) [^1]
 - pin `go-scalr` dependency to proper commit: `go get github.com/Scalr/go-scalr@<commit-sha>` [^1]
 - add `scalr/resource_scalr_<name>.go`, `scalr/datasource_scalr_<name>.go`, implement schemas and methods
+
+  > [!IMPORTANT]
+  > Always fill in the `Description` field for the resource/datasource schema and for every attribute in it
+  with clean and useful information. This will be collected and compiled into the documentation website.
 - add new resources to [provider schema](./scalr/provider.go)
-- add corresponing `*_test.go` files for each new module with acceptance tests
-- add new documentation: `docs/resources/scalr_<name>.md`, `docs/data-sources/scalr_<name>.md` following the common template [^2]
+- add corresponding `*_test.go` files for each new module with acceptance tests
+- add the example files for the documentation, see the `examples` folder for the reference
+- if the resource needs a more complex doc page, this can be done by adding a new template in the `templates` folder
+- run `go generate` command from repository root to compile the documentation
 - [update the changelog](#updating-the-changelog)
 
 ## Updating the changelog
@@ -101,7 +107,7 @@ API object relationships in provider resource schema usually follow the rule:
 
 When in doubt, it is always a good advice to look through some good examples of existing terraform plugins, such as [terraform-provider-aws](https://github.com/hashicorp/terraform-provider-aws), [terraform-provider-auth0](https://github.com/auth0/terraform-provider-auth0), [terraform-provider-tfe](https://github.com/hashicorp/terraform-provider-tfe)
 
-### Rules to follow [^3]
+### Rules to follow [^2]
 
 - avoid using deprecated features
 - use context-aware function versions where it is intended (resource CRUD, etc),
@@ -123,7 +129,7 @@ rather than using create or update logic which only triggers during apply
   - when a slice must be initialized with an empty slice instead of zero value,
     prefer allocating it with `make` function instead of empty slice literal (`make([]int, 0)` over `[]int{}`)
 
-    > **Note**
+    > [!NOTE]
     > When choosing the initial value for slice, take into account that zero-value slice marshals into `null`,
     while an empty slice will produce `[]`.
 - always cleanup `go.sum` after modifying project dependencies:
@@ -146,5 +152,4 @@ Considering a scenario where there are two resources and each resource has a rel
 It can be solved by making one of these attributes `Computed` and introducing a new resource that manages the state of this relation. Refer to `scalr_provider_configuration`, `scalr_provider_configuration_default` and `scalr_environment.default_provider_configurations` for an example.
 
 [^1]: Approach will change in the future when the autogenerated API client will be introduced
-[^2]: Autogenerating of the documentation is planned for implementation, the step will updated when ready
-[^3]: Some advices are relevant only for SDKv2-based plugin; the migration to the Terraform Plugin Framework is already scheduled and this doc will be continiously updated and supplemented accordingly
+[^2]: Some advices are relevant only for SDKv2-based plugin; the migration to the Terraform Plugin Framework is already scheduled and this doc will be continiously updated and supplemented accordingly

README.md

@@ -16,12 +16,12 @@ Follow the instructions on the [official documentation page](https://docs.scalr.
 ## Developing the provider
 ### Requirements
 - [Terraform](https://www.terraform.io/downloads.html) >= 0.15.x
-- [Go](https://golang.org/doc/install) >= 1.18
+- [Go](https://golang.org/doc/install) >= 1.19
 - [jq](https://stedolan.github.io/jq/) >= 1.0
 
 ### Setup
 If you wish to work on the provider, you'll first need [Go](http://www.golang.org) installed
-on your machine (version 1.18+ is *required*).
+on your machine (version 1.19+ is *required*).
 
 Clone the repository:
 ```sh

docs/data-sources/access_policy.md

@@ -0,0 +1,58 @@
+---
+title: "scalr_access_policy"
+categorySlug: "scalr-terraform-provider"
+slug: "provider_datasource_scalr_access_policy"
+parentDocSlug: "provider_datasources"
+hidden: false
+order: 1
+---
+## Data Source Overview
+
+This data source is used to retrieve details of a single access policy by id.
+
+## Example Usage
+
+```terraform
+data "scalr_access_policy" "example" {
+  id = "ap-xxxxxxxxxx"
+}
+
+output "scope_id" {
+  value = data.scalr_access_policy.example.scope[0].id
+}
+
+output "subject_id" {
+  value = data.scalr_access_policy.example.subject[0].id
+}
+```
+
+<!-- Manually filling the schema here because of https://github.com/hashicorp/terraform-plugin-docs/issues/28 -->
+## Schema
+
+### Required
+
+- `id` (String) The access policy ID.
+
+### Read-Only
+
+- `is_system` (Boolean)
+- `role_ids` (List of String) The list of the role IDs.
+- `scope` (List of Object) Defines the scope where access policy is applied. (see [below for nested schema](#nestedatt--scope))
+- `subject` (List of Object) Defines the subject of the access policy. (see [below for nested schema](#nestedatt--subject))
+
+<a id="nestedatt--scope"></a>
+### Nested Schema for `scope`
+
+Read-Only:
+
+- `id` (String) The scope ID, `acc-<RANDOM STRING>` for account, `env-<RANDOM STRING>` for environment, `ws-<RANDOM STRING>` for workspace.
+- `type` (String) The scope identity type, is one of `account`, `environment`, or `workspace`.
+
+
+<a id="nestedatt--subject"></a>
+### Nested Schema for `subject`
+
+Read-Only:
+
+- `id` (String) The subject ID, `user-<RANDOM STRING>` for user, `team-<RANDOM STRING>` for team, `sa-<RANDOM STRING>` for service account.
+- `type` (String) The subject type, is one of `user`, `team`, or `service_account`.

docs/data-sources/agent_pool.md

@@ -0,0 +1,40 @@
+---
+title: "scalr_agent_pool"
+categorySlug: "scalr-terraform-provider"
+slug: "provider_datasource_scalr_agent_pool"
+parentDocSlug: "provider_datasources"
+hidden: false
+order: 2
+---
+## Data Source Overview
+
+Retrieves the details of an agent pool.
+
+## Example Usage
+
+```terraform
+data "scalr_agent_pool" "example1" {
+  id         = "apool-xxxxxxxxxx"
+  account_id = "acc-xxxxxxxxxx"
+}
+
+data "scalr_agent_pool" "example2" {
+  name       = "default-pool"
+  account_id = "acc-xxxxxxxxxx"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `account_id` (String) An identifier of the Scalr account.
+- `environment_id` (String) An identifier of the Scalr environment.
+- `id` (String) ID of the agent pool.
+- `name` (String) A name of the agent pool.
+- `vcs_enabled` (Boolean) Indicates whether the VCS support is enabled for agents in the pool.
+
+### Read-Only
+
+- `workspace_ids` (List of String) The list of IDs of linked workspaces.

docs/data-sources/current_account.md

@@ -0,0 +1,27 @@
+---
+title: "scalr_current_account"
+categorySlug: "scalr-terraform-provider"
+slug: "provider_datasource_scalr_current_account"
+parentDocSlug: "provider_datasources"
+hidden: false
+order: 3
+---
+## Data Source Overview
+
+Retrieves the details of current account when using Scalr remote backend.
+
+No arguments are required. The data source returns details of the current account based on the `SCALR_ACCOUNT_ID` environment variable that is automatically exported in the Scalr remote backend.
+
+## Example Usage
+
+```terraform
+data "scalr_current_account" "account" {}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `id` (String) The identifier of the account.
+- `name` (String) The name of the account.