Skip to content

Document Relationships Between Terraform Commands, Protocol RPCs, and Framework Functionality #618

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.

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

Merged
merged 14 commits into from
Jan 31, 2023
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ website/local:
$(MAKE) -C website website/local

# Run this to generate a new local Docker image.
# Use a local Docker image if you want to verify that images embedded in pages render correctly.
.PHONY: website/build-local
website/build-local:
$(MAKE) -C website website/build-local
4 changes: 4 additions & 0 deletions website/data/plugin-framework-nav-data.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
}
]
},
{
"title": "Protocol RPCs",
"path": "rpcs"
},
Copy link
Contributor

Choose a reason for hiding this comment

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

Just to raise a slight concern: I'm a little worried that this page is a little too detailed in its current form to be the first potential page of the navigation. The information is real nice (e.g. relating Terraform commands to how they interact with provider code), but I think it might completely overwhelm newer developers with a lot of implementation bits that are not fully necessary for them to successfully develop a provider. I'm not sure I have the best constructive feedback yet on how to address that potential concern though. 🙁

One thing is that we currently have pages for each of the provider implementation details, such as Providers > Validating Configuration. Maybe some of this content could exist towards the bottom of those for advanced readers so its a little more self-contained depending on what a developer is wanting to do. Otherwise, I think we should consider how to link those pages back to this information in some form.

I don't think doing the above would fully alleviate the need for some of the higher level information of this page, but it might help quell the information overload issue by colocating the nitty-gritty RPC details as an "implementation details" section for each of the other pages that has a call out that this information is provided only for developers wanting a more technical deep dive.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Might be best if we discuss how we want to proceed here. I'm more than happy to add information and/or links wherever you think would best serve the reader.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Have refactored following discussion to include a new Internals section in the documentation and link to the RPCs and Framework Functionality page from other pages in the docs.

{
"title": "Provider Servers",
"path": "provider-servers"
Expand Down
206 changes: 206 additions & 0 deletions website/docs/plugin/framework/rpcs.mdx

Large diffs are not rendered by default.

Binary file added website/img/apply-resource-change-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/configure-provider-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/configure-provider-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/get-provider-schema-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/get-provider-schema-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/plan-resource-change-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/plan-resource-change-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/read-data-source-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/read-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/read-resource-detail.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added website/img/validate-config-overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.