chore(docs): use default template where possible for Fabric docs #764

ctreatma · 2024-08-28T20:49:58Z

This removes custom templates for some Fabric data sources and resources to avoid missed docs changes due to hard-coded docs templates, which partially addresses #724.

Changes made here are: in cases where there is a single example file,

rename that example to align with conventional paths for examples in tfplugindocs
remove the custom template so that the default template is used
update the resource/data source description in code to match what was in the previous docs

ctreatma · 2024-08-28T20:54:12Z

@equinix/governor-digin-fabric for your reference (and/or review). I noticed that #762 makes changes to the schema but doesn't include the corresponding docs updates because these templates are all currently hard-coded.

ocobles

lgtm! However there few golangci-lint errors that we may want to address in a different PR

ctreatma · 2024-08-30T15:18:35Z

lgtm! However there few golangci-lint errors that we may want to address in a different PR

Rather than bypass the required status check, since it's already limited to files that are changed in the PR, I fixed the issues.

Took a little more back-and-forth than I would have liked due to linter config. I have a separate PR to adjust linter config here: #766

displague · 2024-08-30T16:21:53Z

docs/data-sources/fabric_cloud_router.md

 ---

-# equinix_fabric_clouder_router (Data Source)


displague

Aside from some callouts, the move to a fully generated doc brought all-around improvement. Enums and fields that were missed are now documented and will stay documented through schema changes.

displague · 2024-08-30T16:25:22Z

docs/data-sources/fabric_cloud_routers.md

 subcategory: "Fabric"
-description: |-


Can we add description into the resource definition to get matching markdown results? This is a small description, but we could miss some handy documentation links or greater details if they were specified on other resources (I'll keep an eye out in this review).

I presume the default page_title is as good or better.

The descriptions are in the body, they are not being rendered in the markdown frontmatter.

https://github.com/equinix/terraform-provider-equinix/pull/764/files?diff=split&w=1#diff-329a375d2de207d4b7529b502ca8930f5636802bc6aa8934c848ed2972a7260aR32-R36

Is this intended? The first line of non-title markdown body text ends up getting the same treatment as a description frontmatter so it would be redundant to capture it as front-matter?

The description frontmatter is not used by the registry: https://developer.hashicorp.com/terraform/registry/providers/docs#yaml-frontmatter

The page_title is used, but based on current page titles in the registry, the value we are specifying in data source and resource pages is equivalent to not specifying that attribute at all.

displague · 2024-08-30T16:26:10Z

docs/data-sources/fabric_connection.md

 ### Nested Schema for `a_side.access_point`

 Read-Only:

 - `account` (Set of Object) (see [below for nested schema](#nestedobjatt--a_side--access_point--account))
 - `authentication_key` (String)
- `gateway` (Set of Object, Deprecated) **Deprecated** `gateway` Use `router` attribute instead (see [below for nested schema](#nestedobjatt--a_side--access_point--gateway))


we lose a documented deprecation flag. Is the field not marked as deprecated? (also in z_side docs)

It is marked appropriately, but because it is a nested field the descriptions and further details aren't picked up by tfplugindocs. Just the name of the attribute and the type.

Actually, there may be another reason for this. The data_source isn't showing descriptions for any of the nested attributes even though the resource schema displays them. Might be because of the way we're changing attribute behavior to computed and then setting the data_source value.

Resource attributes are showing nested descriptions.

displague · 2024-08-30T16:28:23Z

docs/resources/fabric_cloud_router.md

@@ -60,7 +55,7 @@ resource "equinix_fabric_cloud_router" "new_cloud_router"{

 - `description` (String) Customer-provided Fabric Cloud Router description
 - `href` (String) Fabric Cloud Router URI information
- `order` (Block Set, Min: 1, Max: 1) Order information related to this Fabric Cloud Router (see [below for nested schema](#nestedblock--order))


Min:1 will be lost. Not included in spec? Intended? (perhaps the documentation template isn't reflecting it)

Order is optional so it shouldn't have a minimum of 1 anyway. This is intended.

thogarty

LGTM. Can be shipped.

thogarty · 2024-09-09T20:33:56Z

docs/data-sources/fabric_connection.md

 ### Nested Schema for `a_side.access_point`

 Read-Only:

 - `account` (Set of Object) (see [below for nested schema](#nestedobjatt--a_side--access_point--account))
 - `authentication_key` (String)
- `gateway` (Set of Object, Deprecated) **Deprecated** `gateway` Use `router` attribute instead (see [below for nested schema](#nestedobjatt--a_side--access_point--gateway))


Actually, there may be another reason for this. The data_source isn't showing descriptions for any of the nested attributes even though the resource schema displays them. Might be because of the way we're changing attribute behavior to computed and then setting the data_source value.

Resource attributes are showing nested descriptions.

thogarty · 2024-09-09T20:34:02Z

docs/resources/fabric_cloud_router.md

@@ -60,7 +55,7 @@ resource "equinix_fabric_cloud_router" "new_cloud_router"{

 - `description` (String) Customer-provided Fabric Cloud Router description
 - `href` (String) Fabric Cloud Router URI information
- `order` (Block Set, Min: 1, Max: 1) Order information related to this Fabric Cloud Router (see [below for nested schema](#nestedblock--order))


Order is optional so it shouldn't have a minimum of 1 anyway. This is intended.

This renames example terraform files in cases where there is exactly one example for a Fabric resource or data source. Renaming these files brings them fully in line with the tfplugindocs conventional paths, which means we no longer need a custom template for each resource or data source.

ctreatma requested a review from a team as a code owner August 28, 2024 20:49

ctreatma temporarily deployed to internal August 28, 2024 20:50 — with GitHub Actions Inactive

ocobles previously approved these changes Aug 30, 2024

View reviewed changes

ctreatma dismissed ocobles’s stale review via fbe3d00 August 30, 2024 14:40

ctreatma temporarily deployed to internal August 30, 2024 14:40 — with GitHub Actions Inactive

ctreatma force-pushed the fabric-default-template branch from fbe3d00 to be2ee47 Compare August 30, 2024 14:44

ctreatma temporarily deployed to internal August 30, 2024 14:44 — with GitHub Actions Inactive

ctreatma temporarily deployed to internal August 30, 2024 15:02 — with GitHub Actions Inactive

ctreatma temporarily deployed to internal August 30, 2024 15:10 — with GitHub Actions Inactive

ctreatma mentioned this pull request Aug 30, 2024

chore(ci): tell golangci-lint to report all issues #766

Merged

ctreatma force-pushed the fabric-default-template branch from 5377cdd to ca3dd37 Compare August 30, 2024 15:14

ctreatma temporarily deployed to internal August 30, 2024 15:15 — with GitHub Actions Inactive

ocobles approved these changes Aug 30, 2024

View reviewed changes

ctreatma force-pushed the fabric-default-template branch from ca3dd37 to 2bc85e0 Compare August 30, 2024 15:57

ctreatma temporarily deployed to internal August 30, 2024 15:57 — with GitHub Actions Inactive

displague reviewed Aug 30, 2024

View reviewed changes

docs/data-sources/fabric_cloud_router.md

---

# equinix_fabric_clouder_router (Data Source)

Copy link

Member

displague Aug 30, 2024

Choose a reason for hiding this comment

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

it rhymes

displague reviewed Aug 30, 2024

View reviewed changes

thogarty approved these changes Sep 9, 2024

View reviewed changes

ctreatma added 3 commits September 9, 2024 16:35

move description to docs

45a6b22

regenerate docs using common template

82e4b5b

ctreatma added 3 commits September 9, 2024 16:35

fix lint issues in touched files

ccc5c95

fix description for service profile data sources

543bd90

more linter fixes

5f8a46c

ctreatma force-pushed the fabric-default-template branch from 2bc85e0 to 5f8a46c Compare September 9, 2024 21:35

ctreatma temporarily deployed to internal September 9, 2024 21:35 — with GitHub Actions Inactive

ctreatma merged commit 4b0785b into main Sep 9, 2024
8 of 11 checks passed

ctreatma deleted the fabric-default-template branch September 9, 2024 21:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(docs): use default template where possible for Fabric docs #764

chore(docs): use default template where possible for Fabric docs #764

ctreatma commented Aug 28, 2024 •

edited

Loading

ctreatma commented Aug 28, 2024

ocobles left a comment •

edited

Loading

ctreatma commented Aug 30, 2024

displague Aug 30, 2024

displague left a comment

displague Aug 30, 2024

displague Aug 30, 2024

ctreatma Aug 30, 2024

displague Aug 30, 2024

thogarty Sep 9, 2024

thogarty Sep 9, 2024

displague Aug 30, 2024

thogarty Sep 9, 2024

thogarty left a comment

thogarty Sep 9, 2024

thogarty Sep 9, 2024

chore(docs): use default template where possible for Fabric docs #764

chore(docs): use default template where possible for Fabric docs #764

Conversation

ctreatma commented Aug 28, 2024 • edited Loading

ctreatma commented Aug 28, 2024

ocobles left a comment • edited Loading

Choose a reason for hiding this comment

ctreatma commented Aug 30, 2024

Choose a reason for hiding this comment

displague left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thogarty left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ctreatma commented Aug 28, 2024 •

edited

Loading

ocobles left a comment •

edited

Loading