docs: updating documentation for NIMf connection example in Metal Connection Resource #734

srushti-patl · 2024-07-18T21:19:37Z

-Updated template, doc and schema files for NIMF connection Documentation change:

resources/fabric-conenction
respurces/metal-connection
data-sources/metal-connection
Update example file names for metal and fabric connection resource

…ction Resource

ctreatma

These changes need to be made in the templates directory; once the templates are updated, you can run make docs to regenerate the docs from the updated templates.

In the templates, you should consider replacing the hard-coded attribute listing with {{ .SchemaMarkdown | trimspace }} (see #724).

thogarty

You should update the descriptions in the direct schema of each data_source/resource and then use the schema markdown suggestion to regenerate the attribute list directly from what the schema is now. That way it will be dynamically updated without having to make docs changes manually.

thogarty · 2024-07-18T23:01:58Z

templates/data-sources/metal_connection.md.tmpl

@@ -56,3 +56,4 @@ In addition to all arguments above, the following attributes are exported:
  * `link_status` - Port link status.
  * `virtual_circuit_ids` - List of IDs of virtual cicruits attached to this port.
 * `token` - (Deprecated) Fabric Token required to configure the connection in Equinix Fabric with the [equinix_fabric_connection](../resources/fabric_connection.md) resource or from the [Equinix Fabric Portal](https://fabric.equinix.com/dashboard). If your organization already has connection service tokens enabled, use `service_tokens` instead.
+* `authorization_code` - Fabric Authorization Code to configure the NIMF connection in Equinix Fabric with the [equinix_fabric_connection](../resources/fabric_connection.md) resource or from the [Equinix Fabric Portal](https://fabric.equinix.com/dashboard).


Instead of manually updating this I would recommend using {{ .SchemaMarkdown }} to replace the attributes list and have it build the correct attribute from the description in the schema.

I have used {{ .SchemaMarkdown }} to replace attributes list but manually updated attribute reference for metal connection

thogarty · 2024-07-18T23:02:08Z

templates/resources/metal_connection.md.tmpl

@@ -57,3 +65,4 @@ In addition to all arguments above, the following attributes are exported:
 * `ports` - List of connection ports - primary (`ports[0]`) and secondary (`ports[1]`). Schema of port is described in documentation of the [equinix_metal_connection datasource](../data-sources/metal_connection.md).
 * `service_tokens` - List of connection service tokens with attributes required to configure the connection in Equinix Fabric with the [equinix_fabric_connection](./fabric_connection.md) resource or from the [Equinix Fabric Portal](https://fabric.equinix.com/dashboard). Scehma of service_token is described in documentation of the [equinix_metal_connection datasource](../data-sources/metal_connection.md).
 * `token` - (Deprecated) Fabric Token required to configure the connection in Equinix Fabric with the [equinix_fabric_connection](./fabric_connection.md) resource or from the [Equinix Fabric Portal](https://fabric.equinix.com/dashboard). If your organization already has connection service tokens enabled, use `service_tokens` instead.
+* `authorization_code` - Fabric Authorization code to configure the NIMF connection with Cloud Service Provider through Equinix Fabric with the [equinix_fabric_connection](./fabric_connection.md) resource from the [Equinix Developer Portal](https://developer.equinix.com/dev-docs/fabric/getting-started/fabric-v4-apis/connect-metal-to-amazon-web-services).


Instead of manually updating this I would recommend using {{ .SchemaMarkdown }} to replace the attributes list and have it build the correct attribute from the description in the schema.

I have used {{ .SchemaMarkdown }} to replace attributes list but manually updated attribute reference for metal connection

thogarty · 2024-07-18T23:02:30Z

templates/resources/fabric_connection.md.tmpl

@@ -149,7 +157,7 @@ Optional:

 Optional:

- `authentication_key` (String) Authentication key for provider based connections
+- `authentication_key` (String) Authentication key for provider based connections or Metal NIMF connections


While you're in here; instead of manually updating this I would recommend using {{ .SchemaMarkdown }} to replace the attributes list and have it build the correct attribute from the description in the schema.

ctreatma · 2024-07-19T16:30:13Z

templates/resources/metal_connection.md.tmpl

@@ -30,6 +30,14 @@ Use this resource to request the creation an Interconnection asset to connect wi

 {{tffile "examples/resources/metal_connection/example_3.tf"}}

+### Shared Connection with authorization_code Non-redundant NIMF connection from Equinix Metal to a Cloud Service Provider via Equinix Fabric Port
+
+{{tffile "examples/resources/metal_connection/example_4.tf"}}


Nit: the docs migrator doesn't know the purpose of individual example files, but we do; I recommend using more descriptive file names for these example files, such as shared_nimf_to_csp.tf and shared_nimf_from_fcr.tf instead of example_<n>.tf. The only time we should use a generic name for an example file is when there is a single example, called example.tf, since that one will be automatically discovered by the generator (with the caveat that the generator has a weird inconsistency in the conventional paths for examples, mentioned in #724).

I have renamed the metal and fabric connection example.

…renaming doc example file names

…' into CXF-97293-NIMF-Documentation-Fix

codecov-commenter · 2024-07-19T21:45:36Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 51.88%. Comparing base (f8c2ab9) to head (1fd29eb).
Report is 11 commits behind head on main.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #734       +/-   ##
===========================================
+ Coverage   34.44%   51.88%   +17.43%     
===========================================
  Files         151      153        +2     
  Lines       20710    20994      +284     
===========================================
+ Hits         7133    10892     +3759     
+ Misses      13415     9672     -3743     
- Partials      162      430      +268

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

thogarty

LGTM. Thanks @srushti-patl

ctreatma · 2024-07-22T14:27:37Z

templates/resources/metal_connection.md.tmpl

-* `tags` - (Optional) String list of tags.
-* `vlans` - (Optional) Only used with shared connection. Vlans to attach. Pass one vlan for Primary/Single connection and two vlans for Redundant connection.
-* `service_token_type` - (Optional) Only used with shared connection. Type of service token to use for the connection, a_side or z_side. (**NOTE: To support the legacy non-automated way to create connections, terraform will not check if `service_token_type` is specified. If your organization already has `service_token_type` enabled, be sure to specify it or the connection will return a legacy connection token instead of a service token**)
+{{ .SchemaMarkdown | trimspace }}

 ## Attributes Reference


This ## Attributes Reference can also be removed; it's part of the .SchemaMarkdown output

ctreatma · 2024-07-22T14:27:54Z

templates/data-sources/metal_connection.md.tmpl

@@ -20,7 +20,7 @@ Use this data source to retrieve a [connection resource](https://metal.equinix.c

 The following arguments are supported:

-* `connection_id` - (Required) ID of the connection resource.
+{{ .SchemaMarkdown | trimspace }}

 ## Attributes Reference


This ## Attributes Reference can also be removed; it's part of the .SchemaMarkdown output

ctreatma · 2024-07-22T14:30:27Z

docs/resources/metal_connection.md

+
+Read-Only:
+
+- `id` (String)


These have lost their description because it was hard-coded in the docs. For the metal_connection docs you could either keep the hard-coded attributes for now or update the resource and data source schemas under internal/resources/metal/connection/ to add the missing descriptions for these properties.

@ctreatma I have kept hard coded attributes for metal_connections docs.

…{ .SchemaMarkdown }}

thogarty

LGTM.

github-actions · 2024-07-23T17:08:37Z

This PR is included in version 2.3.0 🎉

fix:updating documentation for NIMf connection example in Metal Conne…

8d8dfed

…ction Resource

srushti-patl requested review from a team as code owners July 18, 2024 21:19

Merge branch 'main' into CXF-97293-NIMF-Documentation-Fix

0531923

ctreatma requested changes Jul 18, 2024

View reviewed changes

docs: Adding NIMF doc updates to templates

ee13ff1

srushti-patl temporarily deployed to internal July 18, 2024 22:06 — with GitHub Actions Inactive

srushti-patl requested a review from ctreatma July 18, 2024 22:08

Merge branch 'main' into CXF-97293-NIMF-Documentation-Fix

0a76c7c

srushti-patl temporarily deployed to internal July 18, 2024 23:00 — with GitHub Actions Inactive

thogarty requested changes Jul 18, 2024

View reviewed changes

ctreatma reviewed Jul 19, 2024

View reviewed changes

srushti-patl added 2 commits July 19, 2024 14:19

fix: Adding {{ .SchemaMarkdown | trimspace }} into doc templates and …

029b474

…renaming doc example file names

Merge remote-tracking branch 'origin/CXF-97293-NIMF-Documentation-Fix…

1fd29eb

…' into CXF-97293-NIMF-Documentation-Fix

srushti-patl temporarily deployed to internal July 19, 2024 21:19 — with GitHub Actions Inactive

srushti-patl deployed to internal July 19, 2024 21:19 — with GitHub Actions Active

srushti-patl requested review from ctreatma and thogarty July 19, 2024 21:23

thogarty previously approved these changes Jul 19, 2024

View reviewed changes

ctreatma reviewed Jul 22, 2024

View reviewed changes

fix: reverting back changes for generating docs automatically using {…

9dbafe6

…{ .SchemaMarkdown }}

srushti-patl dismissed thogarty’s stale review via 9dbafe6 July 22, 2024 17:34

srushti-patl temporarily deployed to internal July 22, 2024 17:34 — with GitHub Actions Inactive

Merge branch 'main' into CXF-97293-NIMF-Documentation-Fix

c464a72

srushti-patl temporarily deployed to internal July 22, 2024 17:36 — with GitHub Actions Inactive

srushti-patl requested review from ctreatma and thogarty July 22, 2024 17:37

ctreatma approved these changes Jul 22, 2024

View reviewed changes

thogarty approved these changes Jul 22, 2024

View reviewed changes

srushti-patl merged commit e2b34f2 into main Jul 22, 2024
8 of 11 checks passed

srushti-patl deleted the CXF-97293-NIMF-Documentation-Fix branch July 22, 2024 20:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: updating documentation for NIMf connection example in Metal Connection Resource #734

docs: updating documentation for NIMf connection example in Metal Connection Resource #734

srushti-patl commented Jul 18, 2024 •

edited

Loading

ctreatma left a comment

thogarty left a comment

thogarty Jul 18, 2024

srushti-patl Jul 19, 2024

thogarty Jul 18, 2024

srushti-patl Jul 19, 2024

thogarty Jul 18, 2024

ctreatma Jul 19, 2024

srushti-patl Jul 19, 2024

codecov-commenter commented Jul 19, 2024

thogarty left a comment

ctreatma Jul 22, 2024

ctreatma Jul 22, 2024

ctreatma Jul 22, 2024 •

edited

Loading

srushti-patl Jul 22, 2024

thogarty left a comment

github-actions bot commented Jul 23, 2024

docs: updating documentation for NIMf connection example in Metal Connection Resource #734

docs: updating documentation for NIMf connection example in Metal Connection Resource #734

Conversation

srushti-patl commented Jul 18, 2024 • edited Loading

ctreatma left a 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

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

codecov-commenter commented Jul 19, 2024

Codecov Report

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 Jul 22, 2024 • edited Loading

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

github-actions bot commented Jul 23, 2024

srushti-patl commented Jul 18, 2024 •

edited

Loading

ctreatma Jul 22, 2024 •

edited

Loading