Skip to content
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

Write _index.md to local docs dir on Any TF Provider #2717

Open
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

guineveresaenger
Copy link
Contributor

@guineveresaenger guineveresaenger commented Dec 11, 2024

Update: Rebased against #2742 which adds Cobra. Blocked until that merges.

This pull request adds a registryDocs Generator to the initialSetup call for a dynamic provider.

Adjustments to accommodate this change:

  • Because the generation instructions will necessarily include the string terraform, the section needs to be added after the edit rules are applied.
  • The logic to determine which installation instruction to generate is hinged on info.Repository, which is the source repo of the provider. If it doesn't contain "pulumi" then we're dealing with an Any TF provider.
  • _index.md is written to a user-specified (via flag) --indexDocOutDir. This allows us to write to any location in a file system. Leaving this blank prompts the file to only get written to the virtual filesystem in the bridge.
  • An integration test is added that verifies generation and translation of the _index.md file` from hashicorp/random.

@guineveresaenger guineveresaenger self-assigned this Dec 11, 2024
@guineveresaenger guineveresaenger marked this pull request as ready for review December 12, 2024 01:40
@guineveresaenger guineveresaenger requested a review from a team December 12, 2024 01:40
dynamic/main.go Outdated
@@ -94,6 +95,34 @@ func initialSetup() (info.Provider, pfbridge.ProviderMetadata, func() error) {
info.SchemaPostProcessor(&packageSchema.PackageSpec)
}

if fullDocs {
Copy link
Member

Choose a reason for hiding this comment

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

Why are we associating "generate a full schema" with "generate a docs page"? Can we allow them to be set independently?

Suggested change
if fullDocs {
if indexDocsOutDir != "" {

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is meant as an internal feature to generate docs for the registry, where my expectation is we'd always want to do it together.
I almost added it as a default part of the fullDocs flag originally, but wanted to be able to specify an outDir (and not write to a physical file if outDir is unspecified).

dynamic/main.go Outdated
Comment on lines 99 to 100
// Create a custom generator for registry docs (_index.md).
root := afero.NewMemMapFs()
Copy link
Member

Choose a reason for hiding this comment

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

AFAIK, we are just doing this in memory if indexDocsOutDir is ""? We will never save it to disk. Why would we bother doing this at all?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

AIUI, NewMemMapFs is the in-memory option.

@@ -102,6 +132,6 @@ func ParseArgs(args []string) (Args, error) {
remote.Name = args[0]
return Args{Remote: &remote}, nil
default:
return Args{}, fmt.Errorf("expected to be parameterized by 1-3 arguments: <name> [version] [fullDocs=<true|false>]")
return Args{}, fmt.Errorf("expected to be parameterized by 1-4 arguments: <name> [version] [fullDocs=<true|false>] [indexDocOutDir=<path/to/dir>]")
Copy link
Member

Choose a reason for hiding this comment

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

We are getting to the point where we should just slap cobra on this. We can do that in a follow-up PR.

Comment on lines 115 to 126
// ****
// ## Generate Provider
//
// The Foo provider must be installed as a Local Package by following the instructions for Any Terraform Provider: (link)
// ```bash
// pulumi package add terraform-provider org/foo
// ```
// ****
Copy link
Member

Choose a reason for hiding this comment

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

Go's preferred way to add examples is with indentation.

Suggested change
// ****
// ## Generate Provider
//
// The Foo provider must be installed as a Local Package by following the instructions for Any Terraform Provider: (link)
// ```bash
// pulumi package add terraform-provider org/foo
// ```
// ****
// ## Generate Provider
//
// The Foo provider must be installed as a Local Package by following the instructions for Any Terraform Provider: (link)
// ```bash
// pulumi package add terraform-provider org/foo
// ```

Comment on lines 128 to 130
var instructions string
if strings.Contains(sourceRepo, "pulumi") {
instructions = fmt.Sprintf(
Copy link
Member

Choose a reason for hiding this comment

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

You can't return the if expression (since it isn't an expression), but we should return in it.

Suggested change
var instructions string
if strings.Contains(sourceRepo, "pulumi") {
instructions = fmt.Sprintf(
if strings.Contains(sourceRepo, "pulumi") {
return fmt.Sprintf(

@guineveresaenger guineveresaenger force-pushed the guin/add-index-md-dynamic branch 3 times, most recently from dfce611 to d78582a Compare December 13, 2024 02:16
iwahbe and others added 8 commits December 13, 2024 20:04
This allows modules outside of the bridge to test code that uses
`tfbridge.GetLogger`. This will be used by `dynamic`. It may also be used by AWS, which
currently has test code which uses the now moved-to-internal logging.InitContext.
This gets us out of the business of writing flag parsing. This does change the format of
options. Before, they looked like:

```console
$ pulumi package get-schema registry.opentofu.org/owner/provider version fullDocs=true
```

They now look like:

```console
$ pulumi package get-schema -- registry.opentofu.org/owner/provider version --fullDocs
```
clean up installation instructions
@guineveresaenger guineveresaenger force-pushed the guin/add-index-md-dynamic branch from d78582a to 5975878 Compare December 14, 2024 01:32
@guineveresaenger guineveresaenger added the blocked The issue cannot be resolved without 3rd party action. label Dec 14, 2024
Copy link

codecov bot commented Dec 14, 2024

Codecov Report

Attention: Patch coverage is 72.97297% with 10 lines in your changes missing coverage. Please review.

Project coverage is 69.63%. Comparing base (f94f380) to head (5975878).
Report is 3 commits behind head on master.

Files with missing lines Patch % Lines
pkg/bridgetest/logging.go 0.00% 10 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #2717      +/-   ##
==========================================
- Coverage   69.64%   69.63%   -0.01%     
==========================================
  Files         301      302       +1     
  Lines       38726    38757      +31     
==========================================
+ Hits        26969    26987      +18     
- Misses      10240    10252      +12     
- Partials     1517     1518       +1     

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

@iwahbe iwahbe removed the blocked The issue cannot be resolved without 3rd party action. label Dec 16, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants