doc: Adjust documentation of search_deployment resource and data source #1833

andreaangiolillo · 2024-01-12T15:29:08Z

Description

Ticket: https://jira.mongodb.org/browse/CLOUDP-221359

This PR updates the search_deployment doc via make generate-doc

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contribution guidelines
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals, I defined an isolated PR with a relevant title as it will be used in the auto-generated changelog.

Further comments

lantoli · 2024-01-12T15:48:34Z

internal/service/searchdeployment/data_source_search_deployment_schema.go

@@ -9,6 +9,7 @@ import (

 func DataSourceSchema(ctx context.Context) schema.Schema {
 	return schema.Schema{
+		MarkdownDescription: "Provides a Search Deployment data source.",


I thought at the end we would generate both MarkdowDescription and Description cc @AgustinBettati

Actually, I added this manually, we could also move this to the template instead. Wondering if there is a way to get the resource description from the open api spec instead. CC @AgustinBettati in case you know how to do this

looking at the Hashicorp doc https://developer.hashicorp.com/terraform/plugin/code-generation/openapi-generator#generator-config it does not seem possible. I will open an issue on their repo. In the meantime I will remove this field from the schema and move the description to the template

Created this issue hashicorp/terraform-plugin-codegen-openapi#123

Yes I agree moving to template will be the best option for now

lantoli · 2024-01-12T15:50:14Z

website/docs/d/search_deployment.html.markdown

@@ -1,37 +1,77 @@
 ---
 layout: "mongodbatlas"
-page_title: "MongoDB Atlas: search deployment"
-sidebar_current: "docs-mongodbatlas-datasource-search-deployment"
+page_title: "MongoDB Atlas: mongodbatlas_search_deployment"


were these deleted/added headers wrong? should we change them in all resources / ds?

I double-checked this with Zuhair and he confirmed that this metadata is no longer used by Hashicorp. Hashicorp used this metadata for screen readers which does not seem to be the case anymore.

marcosuma · 2024-01-12T17:44:24Z

website/docs/r/search_deployment.html.markdown


-* `instance_size` - (Required) Hardware specification for the search node instance sizes. The [MongoDB Atlas API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/Atlas-Search/operation/createAtlasSearchDeployment) describes the valid values. More details can also be found in the [Search Node Documentation](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution/#search-tier).


Interesting: are we losing some valuable information by removing this?

If the description is not good enough, we should update the open API spec of the endpoint. In this case, I will open a follow-up PR to add "More details can also be found in the Search Node Documentation" to the endpoint. Thanks!

FYI created this ticket https://jira.mongodb.org/browse/CLOUDP-222701 to update the open api spec

marcosuma · 2024-01-12T17:46:45Z

website/docs/r/search_deployment.html.markdown

+
+### Optional
+
+- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))


nit: can you just check that we are not losing some relevant information here with the change of timeouts field compared to how it was before?

IMO we are getting more information for timeouts
.

I see that this does not apply to instance_size. If we think that the description is not good enough, we should update the open API spec of the endpoint

AgustinBettati

Some comments after comparing generated documentation using https://registry.terraform.io/tools/doc-preview

AgustinBettati · 2024-01-15T09:31:18Z

website/docs/d/search_deployment.html.markdown


-### Specs
-* `instance_size` - (Required) Hardware specification for the search node instance sizes. The [MongoDB Atlas API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/Atlas-Search/operation/createAtlasSearchDeployment) describes the valid values. More details can also be found in the [Search Node Documentation](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution/#search-tier).


I would preserve this more detailed description of the instance size attribute as it also references valid values, we can adjust the schema description fields and also include a description override config in the generator_config.yml file.

I was planning to modify this in the open api spec but this may be better. I will also update our doc to make sure this is documented

AgustinBettati · 2024-01-15T09:41:20Z

website/docs/r/search_deployment.html.markdown

-`mongodbatlas_search_deployment` provides a Search Deployment resource. The resource lets you create, edit and delete dedicated search nodes in a cluster.

-> **NOTE:** For details on supported cloud providers and existing limitations you can visit the [Search Node Documentation](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution/#search-nodes-for-workload-isolation).

-> **NOTE:** Only a single search deployment resource can be defined for each cluster.


Would prefer to not remove this content as it is valuable for the docs. Could we add this in the template, or as part of the description field of the schema?

Could you clarify the content that you want to include in the template? is the NOTE?

Yes the 2 NOTE: provide valuable info/clarification.

yes, we should add them in the template in this case

AgustinBettati · 2024-01-15T09:44:23Z

website/docs/r/search_deployment.html.markdown


-* `project_id` - (Required) Unique 24-hexadecimal digit string that identifies your project.
-* `cluster_name` - (Required) Label that identifies the cluster to create search nodes for.


I believe we should preserve this description as it makes more sense within the context of a resource.

andreaangiolillo · 2024-01-15T09:50:09Z

@AgustinBettati I will open a follow-up PR to address these comments.

andreaangiolillo added 2 commits January 12, 2024 15:28

doc: Adjust documentation of search_deployment resource and data source

96c2754

fixes

84993d9

andreaangiolillo requested a review from AgustinBettati January 12, 2024 15:37

andreaangiolillo marked this pull request as ready for review January 12, 2024 15:37

andreaangiolillo requested a review from a team as a code owner January 12, 2024 15:37

andreaangiolillo added 2 commits January 12, 2024 15:45

fixes

625c2a2

fixes

0ec90bd

lantoli reviewed Jan 12, 2024

View reviewed changes

lantoli approved these changes Jan 12, 2024

View reviewed changes

andreaangiolillo added 2 commits January 12, 2024 15:55

fixes

1a7d03c

fixes

b9a3005

marcosuma reviewed Jan 12, 2024

View reviewed changes

andreaangiolillo merged commit 8a5ba5f into master Jan 15, 2024
35 checks passed

andreaangiolillo deleted the CLOUDP-221359_2 branch January 15, 2024 09:35

AgustinBettati reviewed Jan 15, 2024

View reviewed changes

andreaangiolillo mentioned this pull request Jan 15, 2024

chore: Addressed followup comments in #1833 #1836

Merged

12 tasks

andreaangiolillo added a commit that referenced this pull request Jan 15, 2024

chore: Addressed followup comments in #1833 (#1836)

1e371d0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: Adjust documentation of search_deployment resource and data source #1833

doc: Adjust documentation of search_deployment resource and data source #1833

andreaangiolillo commented Jan 12, 2024 •

edited

lantoli Jan 12, 2024

andreaangiolillo Jan 12, 2024

andreaangiolillo Jan 12, 2024

andreaangiolillo Jan 12, 2024

AgustinBettati Jan 15, 2024 •

edited

lantoli Jan 12, 2024

andreaangiolillo Jan 12, 2024 •

edited

marcosuma Jan 12, 2024

andreaangiolillo Jan 15, 2024

andreaangiolillo Jan 15, 2024

marcosuma Jan 12, 2024

andreaangiolillo Jan 15, 2024 •

edited

AgustinBettati left a comment

AgustinBettati Jan 15, 2024

andreaangiolillo Jan 15, 2024

AgustinBettati Jan 15, 2024

andreaangiolillo Jan 15, 2024

AgustinBettati Jan 15, 2024

andreaangiolillo Jan 15, 2024

AgustinBettati Jan 15, 2024

andreaangiolillo commented Jan 15, 2024


		* `instance_size` - (Required) Hardware specification for the search node instance sizes. The [MongoDB Atlas API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/Atlas-Search/operation/createAtlasSearchDeployment) describes the valid values. More details can also be found in the [Search Node Documentation](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution/#search-tier).


		### Optional

		- `timeouts` (Attributes) (see [below for nested schema](#nestedatt--timeouts))


		### Specs
		* `instance_size` - (Required) Hardware specification for the search node instance sizes. The [MongoDB Atlas API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/Atlas-Search/operation/createAtlasSearchDeployment) describes the valid values. More details can also be found in the [Search Node Documentation](https://www.mongodb.com/docs/atlas/cluster-config/multi-cloud-distribution/#search-tier).


		* `project_id` - (Required) Unique 24-hexadecimal digit string that identifies your project.
		* `cluster_name` - (Required) Label that identifies the cluster to create search nodes for.

doc: Adjust documentation of search_deployment resource and data source #1833

doc: Adjust documentation of search_deployment resource and data source #1833

Conversation

andreaangiolillo commented Jan 12, 2024 • edited

Description

Type of change:

Required Checklist:

Further comments

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

AgustinBettati Jan 15, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andreaangiolillo Jan 12, 2024 • edited

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

andreaangiolillo Jan 15, 2024 • edited

Choose a reason for hiding this comment

AgustinBettati 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

andreaangiolillo commented Jan 15, 2024

andreaangiolillo commented Jan 12, 2024 •

edited

AgustinBettati Jan 15, 2024 •

edited

andreaangiolillo Jan 12, 2024 •

edited

andreaangiolillo Jan 15, 2024 •

edited