Auto Generate Docs

Adam Snyderrequested to merge
gen-docs-2 into master

Description

Overview

Fixes #543 (closed)

This PR adds automatic generation for the entire /docs directory, based on the Description schema fields in-code and examples in /examples, as recommended in the Terraform docs guide. It also validates that documentation was generated correctly during the CI workflow.

I am very excited to have this feature, because it will lift a huge burden on PR reviewers to check accuracy of documentation.

Since this PR includes the newly generated documentation, it also fixes all of our existing documentation inaccuracies.

Notes

  • I consolidated our CI workflows for push/pull_request events into a single test.yaml workflow file.
  • The markdown linter is no longer needed, since markdown is now generated. I added new linters for the Terraform and shell code in the /examples directory.
  • The tfproviderlint linter is now enforcing XR005 and XS001 which require descriptions in schemas for the purpose of doc generation.
  • I moved our tool dependencies out of tools.go and into the a /tools directory, which is its own module, in the style of the cloudflare and newrelic providers. The upshot is that make is slightly faster, and we don't pollute our go.mod and go.sum with dev dependencies, and dependabot is still able to handle tool version updates.
  • I added a single make target make reviewable as a one-stop-shop for linting and now generating code, inspired by crossplane.
  • The rest of this PR is just the moving of descriptions from the existing /docs into the code, and then finally re-generating the documentation.
  • This PR does not contain any code changes other than adding descriptions.

PR Checklist

  • Resource attributes match 1:1 the names and structure of the API resource in the GitLab API documentation.
  • Docs are updated with any new resources or attributes, including how to import the resource.
  • New resources should have at minimum a basic test with three steps:
    • Create the resource
    • Update the attributes
    • Import the resource
  • No new //lintignore comments that came from copied code. Linter rules are meant to be enforced on new code.

Merge request reports