Introducing docs generation (#146)

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,8 +8,8 @@
 
 # Test Steps
 
-- [ ] Have you updated the `docs/` folder to match your change?
-- [ ] Have you exercised your change using the `examples/` docker compose setup?
+- [ ] If you've changed documentation, have you run `make generate` to render the `docs/` folder?
+- [ ] Have you exercised your change using the `integration/` docker compose setup?
 
 ```sh
 make testacc

.github/dependabot.yml

@@ -15,3 +15,11 @@ updates:
     groups:
       combined:
         patterns: ["*"]
+
+  - package-ecosystem: "gomod"
+    directory: "/tools"
+    schedule:
+      interval: "weekly"
+    groups:
+      tools:
+        patterns: ["*"]

.github/workflows/test.yml

@@ -56,7 +56,7 @@ jobs:
 
       - name: Set up services
         env:
-          COMPOSE_FILE: ./example/docker-compose.yml
+          COMPOSE_FILE: ./integration/docker-compose.yml
         run: |
           docker-compose build
           docker-compose up -d --force-recreate jenkins
@@ -75,7 +75,7 @@ jobs:
           name: acceptance-coverage
           path: coverage.txt
 
-  example:
+  integration:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -105,24 +105,46 @@ jobs:
 
       - name: Set up services
         env:
-          COMPOSE_FILE: ./example/docker-compose.yml
+          COMPOSE_FILE: ./integration/docker-compose.yml
         run: |
           docker-compose build
           docker-compose up -d --force-recreate jenkins
           while [ "$(docker inspect jenkins-provider-acc --format '{{ .State.Health.Status }}')" != "healthy" ]; do echo "Waiting for Jenkins to start..."; sleep 3; done
 
-      - name: Init example
-        working-directory: example/
+      - name: Init integration
+        working-directory: integration/
         run: terraform init
 
-      - name: Run example
-        working-directory: example/
+      - name: Run integration
+        working-directory: integration/
         run: terraform apply -no-color -auto-approve
 
       - name: Apply again
-        working-directory: example/
+        working-directory: integration/
         run: terraform apply -no-color -auto-approve
 
-      - name: Destroy example
-        working-directory: example/
+      - name: Destroy integration
+        working-directory: integration/
         run: terraform destroy -no-color -auto-approve
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Generate Docs
+        run: make generate
+
+      - name: Verify directory is clean
+        run: test -z "$(git status --porcelain)"
+
+      - name: Error message
+        if: failure()
+        run: |
+          echo ':warning: Generated docs differs from committed docs. Did you forget to run `make generate`?' >> $GITHUB_STEP_SUMMARY

README.md

@@ -43,6 +43,12 @@ In order to run the full suite of Acceptance tests, run `make testacc`. These te
 $ make testacc
 ```
 
+When changing a data source or resource, you may need to update the documentation. This documentation is automatically rendered by https://github.com/hashicorp/terraform-plugin-docs. To trigger a render, execute:
+
+```sh
+$ make generate
+```
+
 ## Attribution
 
 This provider design was originally inspired from the work at [dihedron/terraform-provider-jenkins](https://github.com/dihedron/terraform-provider-jenkins).

docs/index.md

@@ -1,67 +1,35 @@
+---
+page_title: "Provider: Jenkins"
+description: |-
+  The Jenkins provider is used to interact with the Jenkins API.
+---
+
 # Jenkins Provider
 
 The Jenkins provider is used to interact with the Jenkins API. The provider needs to be configured with the proper credentials before it can be used.
 
 ## Example Usage
 
-```hcl
+```terraform
 # Configure the Jenkins Provider
 provider "jenkins" {
-  server_url = "https://jenkins.url" # Or use JENKINS_URL env var
-  username   = "username"            # Or use JENKINS_USERNAME env var
-  password   = "password"            # Or use JENKINS_PASSWORD env var
-  ca_cert = ""                       # Or use JENKINS_CA_CERT env var
-}
-
-# Create a Jenkins job
-resource "jenkins_job" "example" {
-  # ...
+  server_url = "http://localhost:8080" # Or JENKINS_URL env var
+  username   = "admin"                 # Or JENKINS_USERNAME env var
+  password   = "admin"                 # Or JENKINS_PASSWORD env var
+  ca_cert    = ""                      # Or JENKINS_CA_CERT env var
 }
 ```
 
 ## Authentication
 
 Jenkins uses a user/password challenge for authentication. It requires a username & password for determining identity and permissions. This method also supports Jenkins' various authentication plugins, such as GitHub OAuth (through the use of Personal Access Tokens).
 
-### Static credentials ###
-
-Static credentials can be provided by adding a `username` and `password` in-line in the Jenkins provider block:
-
-Usage:
-
-```hcl
-provider "jenkins" {
-  server_url = "https://jenkins.url"
-  username   = "username"
-  password   = "password"
-}
-```
-
-### Environment variables
-
-You can provide your credentials via the `JENKINS_USERNAME` and `JENKINS_PASSWORD`, environment variables. `JENKINS_URL` is also available which will assign the `server_url` property.
-
-```hcl
-provider "jenkins" {}
-```
-
-Usage:
-
-```sh
-$ export JENKINS_URL="https://jenkins.url"
-$ export JENKINS_USERNAME="username"
-$ export JENKINS_PASSWORD="password"
-$ terraform plan
-```
-
-## Argument Reference
-
-In addition to [generic `provider` arguments](https://www.terraform.io/docs/configuration/providers.html) (e.g. `alias` and `version`), the following arguments are supported in the Jenkins `provider` block:
-
-* `server_url` - (Required) This is the Jenkins server URL. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.
-
-* `username` - (Optional) This is Jenkins username for authentication.
+<!-- schema generated by tfplugindocs -->
+## Schema
 
-* `password` - (Optional) This is the Jenkins password for authentication. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.
+### Optional
 
-* `ca_cert` - (Optional) This is the path to the self-signed certificate that may be required in order to authenticate to your Jenkins instance.
+- `ca_cert` (String) The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance.
+- `password` (String) The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.
+- `server_url` (String) The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.
+- `username` (String) The username to authenticate to Jenkins.

examples/data-sources/jenkins_credential_username/data-source.tf

@@ -0,0 +1,4 @@
+data "jenkins_credential_username" "example" {
+  name   = "name"
+  folder = jenkins_folder.example.id
+}

examples/data-sources/jenkins_credential_vault_approle/data-source.tf

@@ -0,0 +1,4 @@
+data "jenkins_credential_vault_approle" "example" {
+  name   = "name"
+  folder = jenkins_folder.example.id
+}

examples/provider/provider.tf

@@ -0,0 +1,7 @@
+# Configure the Jenkins Provider
+provider "jenkins" {
+  server_url = "http://localhost:8080" # Or JENKINS_URL env var
+  username   = "admin"                 # Or JENKINS_USERNAME env var
+  password   = "admin"                 # Or JENKINS_PASSWORD env var
+  ca_cert    = ""                      # Or JENKINS_CA_CERT env var
+}

integration/README.md

@@ -0,0 +1,21 @@
+# Integration
+
+This folder contains an example Dockerized instance of Jenkins for performing manual testing against. It can be used during development to validate against a real Jenkins installation.
+
+## Usage
+
+Start Jenkins with:
+
+```sh
+docker-compose up --detach
+```
+
+And then open it in your web browser at http://localhost:8080.
+
+You can now run `terraform init`, `plan`, `apply`, etc. commands within this directory to test the provider against the Jenkins instance. If you are testing a version of the provider that you are developing locally, ensure that you've run the `make` command in the repository root and followed the provided instructions to configure your machine to use the built binary.
+
+When done with testing, clean up the instance with:
+
+```sh
+docker-compose down --volumes
+```

jenkins/provider.go

@@ -17,22 +17,22 @@ func Provider() *schema.Provider {
 			"server_url": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "The URL of the Jenkins server to connect to.",
+				Description: "The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.",
 			},
 			"ca_cert": {
 				Type:        schema.TypeString,
 				Optional:    true,
-				Description: "The path to the Jenkins self-signed certificate.",
+				Description: "The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance.",
 			},
 			"username": {
 				Type:        schema.TypeString,
 				Optional:    true, // Needs to be optional to be able to run terraform validate without providing credentials
-				Description: "Username to authenticate to Jenkins.",
+				Description: "The username to authenticate to Jenkins.",
 			},
 			"password": {
 				Type:        schema.TypeString,
 				Optional:    true, // Needs to be optional to be able to run terraform validate without providing credentials
-				Description: "Password to authenticate to Jenkins.",
+				Description: "The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.",
 			},
 		},
 

jenkins/provider_framework.go

@@ -32,19 +32,19 @@ func (p *JenkinsProvider) Schema(ctx context.Context, req provider.SchemaRequest
 		Attributes: map[string]schema.Attribute{
 			"server_url": schema.StringAttribute{
 				Optional:    true,
-				Description: "The URL of the Jenkins server to connect to.",
+				Description: "The URL of the Jenkins server to connect to. It should be fully qualified (e.g. `https://...`) and point to the root of the Jenkins server location.",
 			},
 			"ca_cert": schema.StringAttribute{
 				Optional:    true,
-				Description: "The path to the Jenkins self-signed certificate.",
+				Description: "The path to the Jenkins self-signed certificate. It may be required in order to authenticate to your Jenkins instance.",
 			},
 			"username": schema.StringAttribute{
 				Optional:    true, // Needs to be optional to be able to run terraform validate without providing credentials
-				Description: "Username to authenticate to Jenkins.",
+				Description: "The username to authenticate to Jenkins.",
 			},
 			"password": schema.StringAttribute{
 				Optional:    true, // Needs to be optional to be able to run terraform validate without providing credentials
-				Description: "Password to authenticate to Jenkins.",
+				Description: "The password to authenticate to Jenkins. If you are using the GitHub OAuth authentication method, enter your Personal Access Token here.",
 			},
 		},
 	}

makefile

@@ -1,5 +1,5 @@
 BINARY=terraform-provider-jenkins
-export COMPOSE_FILE=./example/docker-compose.yml
+export COMPOSE_FILE=./integration/docker-compose.yml
 
 default: build
 
@@ -17,6 +17,10 @@ build:
 	@echo ""
 	@echo "This should only be used during development. See https://www.terraform.io/docs/commands/cli-config.html#development-overrides-for-provider-developers for details."
 
+# Formats TF files and generates documentation
+generate:
+	cd tools; go generate ./...
+
 # Executes all unit tests for the provider
 test:
 	go test -cover ./...

templates/data-sources/credential_username.md.tmpl

@@ -0,0 +1,28 @@
+# jenkins_credential_username Data Source
+
+Get the attributes of a username credential within Jenkins.
+
+## Example Usage
+
+```hcl
+data "jenkins_credential_username" "example" {
+  name        = "job-name"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `name` - (Required) The name of the resource being read.
+* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store.
+* `folder` - (Optional) The folder namespace containing this resource.
+
+## Attribute Reference
+
+In addition to all arguments above, the following attributes are exported:
+
+* `id` - The full canonical job path, E.G. `/job/job-name`.
+* `description` - A human readable description of the credentials being stored.
+* `scope` - The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM".
+* `username` - The username to be associated with the credentials.

templates/data-sources/credential_vault_approle.md.tmpl

@@ -0,0 +1,32 @@
+# jenkins_credential_vault_approle Data Source
+
+Get the attributes of a Vault AppRole credential within Jenkins.
+
+~> The Jenkins installation that uses this resource is expected to have the [Hashicorp Vault Plugin](https://plugins.jenkins.io/hashicorp-vault-plugin/) installed in their system.
+
+## Example Usage
+
+```hcl
+data "jenkins_credential_vault_approle" "example" {
+  name        = "job-name"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `name` - (Required) The name of the resource being read.
+* `domain` - (Optional) The domain store to place the credentials into. If not set will default to the global credentials store.
+* `folder` - (Optional) The folder namespace containing this resource.
+
+## Attribute Reference
+
+In addition to all arguments above, the following attributes are exported:
+
+* `id` - The full canonical job path, E.G. `/job/job-name`.
+* `description` - A human readable description of the credentials being stored.
+* `scope` - The visibility of the credentials to Jenkins agents. This must be set to either "GLOBAL" or "SYSTEM".
+* `namespace` - The Vault namespace of the approle credential.
+* `path` - The unique name of the approle auth backend. Defaults to `approle`.
+* `role_id` - The role_id to be associated with the credentials.

templates/data-sources/folder.md.tmpl

@@ -0,0 +1,30 @@
+# jenkins_folder Data Source
+
+Get the attributes of a folder within Jenkins.
+
+~> The Jenkins installation that uses this resource is expected to have the [Cloudbees Folders Plugin](https://plugins.jenkins.io/cloudbees-folder) installed in their system.
+
+## Example Usage
+
+```hcl
+data "jenkins_folder" "example" {
+  name        = "folder-name"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `name` - (Required) The name of the folder being read.
+* `folder` - (Optional) The folder namespace containing this folder.
+
+
+## Attribute Reference
+
+In addition to all arguments above, the following attributes are exported:
+
+* `id` - The full canonical folder path, E.G. `/job/parent`.
+* `description` - A block of text describing the folder's purpose.
+* `display_name` - The name of the folder that is displayed in the UI.
+* `template` - A Jenkins-compatible XML template to describe the folder.