Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Auto Generate Docs #802

Merged
merged 7 commits into from
Jan 28, 2022
Merged

Auto Generate Docs #802

merged 7 commits into from
Jan 28, 2022

Conversation

armsnyder
Copy link
Collaborator

@armsnyder armsnyder commented Jan 26, 2022 •
edited

Description

Overview

Fixes #543

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.

@armsnyder armsnyder requested a review from nagyv January 26, 2022 04:14
@armsnyder armsnyder added documentation DX Developer Experience, e.g. contributing, readme, makefile, issue / pr template changes technical debt labels Jan 26, 2022
@armsnyder armsnyder force-pushed the gen-docs-2 branch 3 times, most recently from 762d193 to 3ad9110 Compare January 26, 2022 08:14
timofurrer
timofurrer approved these changes Jan 26, 2022
View reviewed changes
Copy link
Member

@timofurrer timofurrer left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome change!

@armsnyder armsnyder added this to the 3.9.0 milestone Jan 26, 2022
nagyv
nagyv approved these changes Jan 27, 2022
View reviewed changes
Copy link
Collaborator

@nagyv nagyv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@nagyv
Copy link
Collaborator

nagyv commented Jan 27, 2022

@armsnyder I fixed a conflict. Let's merge if everything is green.

@nagyv nagyv mentioned this pull request Jan 27, 2022
Merged
This was referenced Jan 27, 2022
Closed
Closed
@armsnyder
Rework CI automation with doc generation
fd875ee 
- New make target "reviewable" which is the default
- New make target "generate" for generaring provider docs
- Remove tool dependencies from go.mod and go.sum
- Move tool dependencies into /tools directory as a separate Go module to be maintained by dependabot
- Consolidate GitHub Actions for PRs to one file test.yml
- Cache go modules and tools in CI workflows
- Add linters and formatters for examples
@armsnyder
(Auto-generated) Migrate documentation
358bfd3 
- Move attribute documentation to resource schemas
- Move examples to /examples
@armsnyder
Manually add descriptions to schemas that could not be auto-generated
82b81d6 
Handcrafted changes to schema descriptions and examples
@armsnyder
Add back Description fields which got removed by migration tool
5ed07f5
@armsnyder
(Automated) Terraform format all examples
5862436
@armsnyder
(Generated) Generate all documentation from schemas
a49b3ad
@armsnyder armsnyder merged commit 9863a61 into master Jan 28, 2022
@armsnyder armsnyder deleted the gen-docs-2 branch January 28, 2022 02:39
@github-actions
Copy link

github-actions bot commented Feb 4, 2022

This functionality has been released in 3.9.0 of the Terraform GitLab Provider. Please see the Terraform documentation on provider versioning or reach out if you need any assistance upgrading.

For further feature requests or bug reports with this functionality, please create a new GitHub issue. Thank you!

@github-actions github-actions bot locked and limited conversation to collaborators Nov 9, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@nagyv nagyv nagyv approved these changes

@timofurrer timofurrer timofurrer approved these changes

Assignees
No one assigned
Labels
documentation DX Developer Experience, e.g. contributing, readme, makefile, issue / pr template changes technical debt
Milestone
3.9.0
3 participants
@armsnyder @nagyv @timofurrer