Skip to content

Generate docs for datasources#17538

Open
roaks3 wants to merge 1 commit into
mainfrom
generate-ds-docs
Open

Generate docs for datasources#17538
roaks3 wants to merge 1 commit into
mainfrom
generate-ds-docs

Conversation

@roaks3
Copy link
Copy Markdown
Contributor

@roaks3 roaks3 commented May 13, 2026

Part of hashicorp/terraform-provider-google#25987

This adds docs generation for datasources that are generated. The structure is fairly standardized to begin with, and I tried to use the wording that was most commonly used thus far.

The main parts that were more ambiguous:

  1. Examples are hard because (so far) we don't ask the contributor to provide any explicit datasource examples. So to generate the datasource config for tests, we assume we can pull values off of the resource, which works pretty well. I've chosen to do the same for docs simply because it avoids trying to do something more complicated with literals (for example, using a full set of sample values per type, or trying to parse values from the resource example config).
  2. The field descriptions are using what we have for the resource, so some of them are worded slightly weird for a datasource, like referencing creation, and usually include more content than is necessary for the datasource. I considered using firstSentence, but I'm a bit worried about how reliably it will be, especially since most contributors will not check what documentation was generated.

I think in its current state, this should be fine to advance forward and help make datasource creation much easier, but open to feedback of course.

For awareness: this started out as a heavily AI-assisted solution, but by the end I was making a lot of hand edits. The result is a bit of a mix + manual verification and testing that I did.

Release Note Template for Downstream PRs (will be copied)

See Write release notes for guidance.


@modular-magician
Copy link
Copy Markdown
Collaborator

Hi there, I'm the Modular magician. I've detected the following information about your changes for commit b015113:

Diff report

Your PR generated the following diffs in downstream repositories:

Repository Diff Link Changes
google provider View Diff 7 files changed, 159 insertions(+), 106 deletions(-)
google-beta provider View Diff 7 files changed, 159 insertions(+), 106 deletions(-)

Errors

google-beta provider:

  • Error reading file website/docs/d/vmwareengine_datastore_html.markdown

@roaks3
Copy link
Copy Markdown
Contributor Author

roaks3 commented May 13, 2026

I think the template check is actually a bug in the check:

newtmplfiles=$(git diff --name-only --diff-filter=A origin/${GITHUB_BASE_REF} HEAD -- ../../mmv1 | grep .tmpl | sed 's=^=../../=g')
  if [ ! -z "$newtmplfiles" ]; then
...

Looks like it only considers new templates, but would otherwise flag any of our other generic templates.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants