generate examples and docs from Pulumi.yaml files

.github/workflows/release.yml

@@ -58,8 +58,10 @@ jobs:
         uses: jaxxstorm/[email protected]
         with:
           repo: pulumi/pulumictl
-      - name: Build tfgen & provider binaries
-        run: make provider
+      - name: Build tfgen binary
+        run: make only_tfgen
+      - name: Build provider binary
+        run: make only_provider
       - name: Unit-test provider code
         run: make test_provider
       - name: Tar provider binaries

.github/workflows/run-acceptance-tests.yml

@@ -176,8 +176,10 @@ jobs:
       uses: jaxxstorm/[email protected]
       with:
         repo: pulumi/schema-tools
-    - name: Build tfgen & provider binaries
-      run: make provider
+    - name: Build tfgen binary
+      run: make only_tfgen
+    - name: Build provider binary
+      run: make only_provider
     - name: Unit-test provider code
       run: make test_provider
     - if: github.event_name == 'pull_request'

CONTRIBUTING.md

@@ -96,19 +96,23 @@ This project utilizes the [pulumi-terraform-bridge](https://github.com/pulumi/pu
 
 - Generating New Examples
 
-  - In the ./examples/ directory, use the .generate.sh script to create a new example for a specific resource.
-  - Create a subdirectory for the new resource under ./examples/{service}/{resource}.
-  - Copy the script into the new subdirectory and create a Pulumi.yaml file, following the format of existing examples.
-  - After generating the examples, create a new subdirectory named yaml to store the Pulumi.yaml file.
-  - Copy the new example.md file to the docs/resource directory and rename it accordingly.
-  - Update the internal format by removing the tags `chooser` and `choosable` and enclosing the content within a single block `example`:
-
-    ```
-    ## Example Usage
-    {{% example %}}
-      add all SDK examples here
-    {{% /example %}}.
-    ```
+  The bridge plugin has the capability to import Terraform examples, but this functionality is not always reliable. Therefore, we generate examples for all supported languages using the `pulumi convert` command and replace the examples section in the documentation.
+
+  To add or update an example, you need to edit or add a new YAML template at the path `examples/{service-name}/{resource-name}/Pulumi.yaml`. You can use any existing templates as references or consult the [Pulumi YAML Language Reference](https://www.pulumi.com/docs/languages-sdks/yaml/yaml-language-reference/).
+
+  Once you have made your edits, you can use the `make examples` command. This command will:
+  1. Generate the example in all supported languages, which can be found in their respective folders: `examples/{service-name}/{resource-name}/{language-name}` (e.g., go, python, typescript, csharp, java).
+  2. Update the examples that appear in the documentation with a new markdown file in `docs/resource/{resource-name}`.
+
+  If you are adding an example for a new resource, don't forget to include the `ReplaceExamplesSection: true` option in the resource definition in the ProviderInfo mapping in `provider/resources.go`.
+
+  For multiple examples of the same resource, each example must have its own subfolder (see `examples/metal/port/` for reference) with its own Pulumi.yaml. To ensure all examples are correctly displayed in the documentation, update the `scripts/generate_examples.sh` file by adding a new call to the `merge_examples_files` function at the end of the file. For example:
+  ```sh
+  merge_example_files "equinix_metal_port" "equinix_metal_port_hybrid_bonded" "equinix_metal_port_hybrid_unbonded" "equinix_metal_port_layer2_bonded"
+  ```
+  In this command, the first parameter is the resource name, and the subsequent parameters are the normalized names of the examples to be merged. For example, if the name defined within the yaml file is "equinix-metal-port-hybrid-bonded" then its normalized name will be "equinix_metal_port_hybrid_bonded".
+
+  By following these steps, you can ensure that all examples are properly generated and included in the documentation for Pulumi providers.
 
 **Note: Failing upgrade-provider Tool**
 Pulumi provides an [upgrade-provider](https://github.com/pulumi/upgrade-provider) tool that aims to reduce the amount of human intervention necessary for upgrading bridged Pulumi providers. As of March 2024, the upgrade-provider tool may encounter issues (with Equinix provider) due to changes in directory structure during the migration of resources from SDKv2 to Framework. Until this issue is resolved, manual updates are necessary following the outlined steps.

Makefile

@@ -30,7 +30,14 @@ development: install_plugins provider lint_provider build_sdks install_sdks clea
 build: install_plugins provider build_sdks install_sdks
 only_build: build
 
-tfgen: cleanup install_plugins upstream
+only_tfgen: install_plugins upstream build_schema
+tfgen: only_tfgen generate_examples
+
+# Generate examples after the schema is generated
+generate_examples: examples
+
+# Build the tfgen binary and generate the schema
+build_schema:
 	(cd provider && go build -o $(WORKING_DIR)/bin/${TFGEN} -ldflags "-X ${PROJECT}/${VERSION_PATH}=${VERSION}" ${PROJECT}/${PROVIDER_PATH}/cmd/${TFGEN})
 	$(WORKING_DIR)/bin/${TFGEN} schema --out provider/cmd/${PROVIDER}
 	(cd provider && VERSION=$(VERSION) go generate cmd/${PROVIDER}/main.go)
@@ -39,6 +46,9 @@ bin/pulumi-java-gen: .pulumi-java-gen.version
 	pulumictl download-binary -n pulumi-language-java -v v$(shell cat .pulumi-java-gen.version) -r pulumi/pulumi-java
 
 provider: tfgen install_plugins # build the provider binary
+provider: only_provider
+
+only_provider:
 	(cd provider && go build -o $(WORKING_DIR)/bin/${PROVIDER} -ldflags "-X ${PROJECT}/${VERSION_PATH}=${VERSION} -X github.com/equinix/terraform-provider-equinix/version.ProviderVersion=${VERSION}" ${PROJECT}/${PROVIDER_PATH}/cmd/${PROVIDER})
 
 build_sdks: clean build_nodejs build_python build_go build_dotnet build_java # build all the sdks
@@ -59,8 +69,6 @@ build_nodejs: upstream
         cp ../../README.md ../../LICENSE package.json yarn.lock ./bin/ && \
 		sed -i.bak -e "s/\$${VERSION}/$(VERSION)/g" ./bin/package.json
 
-
-
 build_python: PYPI_VERSION := $(shell pulumictl get version --language python)
 build_python: upstream
 	rm -rf sdk/python/
@@ -148,6 +156,12 @@ help:
 clean:
 	rm -rf sdk/{dotnet,nodejs,go,python,java}
 
+install_equinix_plugin: only_provider uninstall_equinix_plugin
+	.pulumi/bin/pulumi plugin install resource equinix $(shell pulumictl get version --language generic) --file $(WORKING_DIR)/bin/$(PROVIDER)
+
+uninstall_equinix_plugin:
+	.pulumi/bin/pulumi plugin rm resource equinix -a -y
+
 install_plugins: .pulumi/bin/pulumi
 	.pulumi/bin/pulumi plugin install resource tls 4.11.0
 	.pulumi/bin/pulumi plugin install resource random 4.14.0
@@ -190,9 +204,12 @@ upstream.rebase:
 .pulumi/bin/pulumi: .pulumi/version
 	curl -fsSL https://get.pulumi.com | HOME=$(WORKING_DIR) sh -s -- --version $(cat .pulumi/version)
 
+examples: install_equinix_plugin
+	scripts/generate_examples.sh
+
 # Compute the version of Pulumi to use by inspecting the Go dependencies of the provider.
 .pulumi/version:
 	@mkdir -p .pulumi
 	@cd provider && go list -f "{{slice .Version 1}}" -m github.com/pulumi/pulumi/pkg/v3 | tee ../$@
 
-.PHONY: development build build_sdks install_go_sdk install_java_sdk install_python_sdk install_sdks only_build build_dotnet build_go build_java build_nodejs build_python clean cleanup help install_dotnet_sdk install_nodejs_sdk install_plugins lint_provider provider test tfgen upstream upstream.finalize upstream.rebase test_provider
+.PHONY: development build build_sdks install_go_sdk install_java_sdk install_python_sdk install_sdks only_build build_dotnet build_go build_java build_nodejs build_python clean cleanup help install_dotnet_sdk install_nodejs_sdk install_equinix_plugin uninstall_equinix_plugin install_plugins lint_provider provider test tfgen upstream upstream.finalize upstream.rebase test_provider examples examples_check