Upgrade documentation hugo theme to v12, adjust layouts and features (#15253)

Author: alex-shpak

.github/workflows/repository-documentation-deploy.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d # v2.6.0
         with:
-          hugo-version: '0.136.5'
+          hugo-version: '0.150.0'
           extended: true
 
       - name: Build

.github/workflows/repository-documentation-test.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@16361eb4acea8698b220b76c0d4e84e1fd22c61d # v2.6.0
         with:
-          hugo-version: '0.136.5'
+          hugo-version: '0.150.0'
           extended: true
 
       - name: Build

docs/README.md

@@ -6,9 +6,9 @@ To view locally:
    [Go](https://go.dev/doc/install), and [Dart Sass](https://gohugo.io/hugo-pipes/transpile-sass-to-css/#dart-sass).
    You require these prerequisites for installing Hugo.
 
-1. Install Hugo v0.136.5:
+1. Install Hugo v0.150.0:
    ```bash
-   CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.136.5
+   CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.150.0
    ```
 
 1. Restart your terminal.
@@ -38,10 +38,17 @@ If you are having deployment issues, try to reset your hugo module cache.
 * `hugo mod clean`
 
 To upgrade the theme version:
-1. find the version you want at https://github.com/alex-shpak/hugo-book/commits/master
+1. Find the version you want at https://github.com/alex-shpak/hugo-book/releases
 2. Run the following
-```bash
-go get github.com/alex-shpak/hugo-book@{{commit_hash}}
-## example
-## go get github.com/alex-shpak/hugo-book@d86d5e70c7c0d787675b13d9aee749c1a8b34776
-```
+   ```bash
+   hugo mod get github.com/alex-shpak/hugo-book/${module_version}
+   ```
+   Example:
+   ```
+   hugo mod get github.com/alex-shpak/hugo-book/v12
+   ```
+   Or to get specific commit tagged with v12.0.0
+   ```bash
+   hugo mod get github.com/alex-shpak/hugo-book/[email protected]
+   ```
+

docs/assets/icons/report.svg

@@ -1,4 +1,6 @@
 ---
 title: "Best practices"
 weight: 60
+params:
+  bookCollapseSection: true
 ---

docs/content/best-practices/_index.md

@@ -5,9 +5,8 @@ weight: 20
 
 # Deletion behaviors
 
-{{< hint info >}}
-**Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
-{{< /hint >}}
+> [!NOTE]
+> **Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
 
 ## Mitigating data loss risk via deletion_protection {#deletion_protection}
 
@@ -26,9 +25,8 @@ Resources that do not have a significant risk of unrecoverable data loss or simi
 
 See [Client-side fields]({{< ref "/develop/client-side-fields" >}}) for information about adding `deletion_protection` fields.
 
-{{< hint info >}}
-**Note:** The previous best practice was a field called `force_delete` that defaulted to `false`. This is still present on some resources for backwards-compatibility reasons, but `deletion_protection` is preferred going forward.
-{{< /hint >}}
+> [!NOTE]
+> **Note:** The previous best practice was a field called `force_delete` that defaulted to `false`. This is still present on some resources for backwards-compatibility reasons, but `deletion_protection` is preferred going forward.
 
 ## Deletion policy {#deletion_policy}
 

docs/content/best-practices/deletion-behaviors.md

@@ -8,9 +8,8 @@ aliases:
 
 # Immutable fields
 
-{{< hint info >}}
-**Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
-{{< /hint >}}
+> [!NOTE]
+> **Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
 
 [`ForceNew`](https://developer.hashicorp.com/terraform/intro#how-does-terraform-work) in a Terraform resource schema attribute that indicates that a field is immutable – that is, that a change to the field requires the resource to be destroyed and recreated.
 

docs/content/best-practices/immutable-fields.md

@@ -5,9 +5,8 @@ weight: 30
 
 # Add labels and annotations support
 
-{{< hint info >}}
-**Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
-{{< /hint >}}
+> [!NOTE]
+> **Note:** This page covers best practices guidance for the Terraform provider for Google Cloud, which is used to ensure a consistent UX for Terraform users across providers or GCP users across the Google provider. Generally, this guidance should be followed and exceptions should be clearly demarcated / discussed.
 
 The new labels model and the new annotations model are introduced in [Terraform provider for Google Cloud 5.0.0](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/version_5_upgrade#provider).
 
@@ -29,83 +28,83 @@ When adding a new `labels` field, please make the changes below to support the n
 
 1. Use the type `KeyValueLabels` for the standard resource `labels` field. The standard resource `labels` field could be the top level `labels` field or the nested `labels` field inside the top level `metadata` field. Don't add `default_from_api: true` to this field or don't use this type for other `labels` fields in the resource. `KeyValueLabels` will add all of changes required for the new model automatically.
 
-```yaml
- - name: 'labels'
-   type: KeyValueLabels
-   description: |
-   The labels associated with this dataset. You can use these to
-   organize and group your datasets.
-```
+   ```yaml
+    - name: 'labels'
+      type: KeyValueLabels
+      description: |
+      The labels associated with this dataset. You can use these to
+      organize and group your datasets.
+   ```
 2. In the handwritten acceptance tests, add `labels` and `terraform_labels` to `ImportStateVerifyIgnore` if `labels` field is in the configuration.
 
-```go
-ImportStateVerifyIgnore: []string{"labels", "terraform_labels"}, 
-```
+   ```go
+   ImportStateVerifyIgnore: []string{"labels", "terraform_labels"}, 
+   ```
 3. In the corresponding data source, after the resource read method, call the function `tpgresource.SetDataSourceLabels(d)` to make `labels` and `terraform_labels` have all of the labels on the resource.
 
-```go
-err = resourceArtifactRegistryRepositoryRead(d, meta)
-if err != nil {
-   return err
-}
+   ```go
+   err = resourceArtifactRegistryRepositoryRead(d, meta)
+   if err != nil {
+      return err
+   }
 
-if err := tpgresource.SetDataSourceLabels(d); err != nil {
-   return err
-}
-```
+   if err := tpgresource.SetDataSourceLabels(d); err != nil {
+      return err
+   }
+   ```
 
 ### Handwritten resources
 
 1. Add `tpgresource.SetLabelsDiff`  to `CustomizeDiff` of the resource.
-```go
-CustomizeDiff: customdiff.All(
-   tpgresource.SetLabelsDiff,
-),
-```
+   ```go
+   CustomizeDiff: customdiff.All(
+      tpgresource.SetLabelsDiff,
+   ),
+   ```
 2. Add `labels` field and add more attributes (such as `ForceNew: true,`, `Set: schema.HashString,`) to this field if necessary.
-```go
-"labels": {
-   Type:     schema.TypeMap,
-   Optional: true,
-   Elem:     &schema.Schema{Type: schema.TypeString},
-   Description: `A set of key/value label pairs to assign to the project.
-   
-   **Note**: This field is non-authoritative, and will only manage the labels present in your configuration.
-   Please refer to the field 'effective_labels' for all of the labels present on the resource.`,
-},
-```
+   ```go
+   "labels": {
+      Type:     schema.TypeMap,
+      Optional: true,
+      Elem:     &schema.Schema{Type: schema.TypeString},
+      Description: `A set of key/value label pairs to assign to the project.
+      
+      **Note**: This field is non-authoritative, and will only manage the labels present in your configuration.
+      Please refer to the field 'effective_labels' for all of the labels present on the resource.`,
+   },
+   ```
 3. Add output only field `terraform_labels` and add more attributes (such as `Set: schema.HashString,`) to this field if necessary. Don't add `ForceNew:true,` to this field.
-```go
-"terraform_labels": {
-   Type:        schema.TypeMap,
-   Computed:    true,
-   Description: `The combination of labels configured directly on the resource and default labels configured on the provider.`,
-   Elem:        &schema.Schema{Type: schema.TypeString},
-},
-```
+   ```go
+   "terraform_labels": {
+      Type:        schema.TypeMap,
+      Computed:    true,
+      Description: `The combination of labels configured directly on the resource and default labels configured on the provider.`,
+      Elem:        &schema.Schema{Type: schema.TypeString},
+   },
+   ```
 4. Add output only field `effective_labels` and add more attributes (such as `ForceNew: true,`, `Set: schema.HashString,`) to this field if necessary.
-```go
-"effective_labels": {
-   Type:        schema.TypeMap,
-   Computed:    true,
-   Description: `All of labels (key/value pairs) present on the resource in GCP, including the labels configured through Terraform, other clients and services.`,
-   Elem:        &schema.Schema{Type: schema.TypeString},
-},
-```
+   ```go
+   "effective_labels": {
+      Type:        schema.TypeMap,
+      Computed:    true,
+      Description: `All of labels (key/value pairs) present on the resource in GCP, including the labels configured through Terraform, other clients and services.`,
+      Elem:        &schema.Schema{Type: schema.TypeString},
+   },
+   ```
 5. In the create method, use the value of `effective_labels` in API request.
 6. In the update method, use the value of `effective_labels` in API request.
 7. In the read mehtod, set `labels`, `terraform_labels` and `effective_labels` to state.
-```go
-if err := tpgresource.SetLabels(res.Labels, d, "labels"); err != nil {
-   return fmt.Errorf("Error setting labels: %s", err)
-}
-if err := tpgresource.SetLabels(res.Labels, d, "terraform_labels"); err != nil {
-   return fmt.Errorf("Error setting terraform_labels: %s", err)
-}
-if err := d.Set("effective_labels", res.Labels); err != nil {
-   return fmt.Errorf("Error setting effective_labels: %s", err)
-}
-```
+   ```go
+   if err := tpgresource.SetLabels(res.Labels, d, "labels"); err != nil {
+      return fmt.Errorf("Error setting labels: %s", err)
+   }
+   if err := tpgresource.SetLabels(res.Labels, d, "terraform_labels"); err != nil {
+      return fmt.Errorf("Error setting terraform_labels: %s", err)
+   }
+   if err := d.Set("effective_labels", res.Labels); err != nil {
+      return fmt.Errorf("Error setting effective_labels: %s", err)
+   }
+   ```
 8. In the handwritten acceptance tests, add `labels` and `terraform_labels` to `ImportStateVerifyIgnore`.
 9. In the corresponding data source, after the resource read method, call the function `tpgresource.SetDataSourceLabels(d)` to make `labels` and `terraform_labels` have all of the labels on the resource.
 10. Add the documentation for these label-related fields.
@@ -117,33 +116,33 @@ When adding a new `annotations` field, please make the changes below below to su
 
 1. Use the type `KeyValueAnnotations` for the standard resource `annotations` field. The standard resource `annotations` field could be the top level `annotations` field or the nested `annotations` field inside the top level `metadata` field. Don't add `default_from_api: true` to this field or don't use this type for other `annotations` fields in the resource. `KeyValueAnnotations` will add all of changes required for the new model automatically.
 
-```yaml
-- name: 'annotations'
-  type: KeyValueAnnotations
-  description: |
-   Client-specified annotations. This is distinct from labels.
-```
+   ```yaml
+   - name: 'annotations'
+     type: KeyValueAnnotations
+     description: |
+       Client-specified annotations. This is distinct from labels.
+   ```
 2. In the handwritten acceptance tests, add `annotations` to `ImportStateVerifyIgnore` if `annotations` field is in the configuration.
 
-```go
-ImportStateVerifyIgnore: []string{"annotations"},
-```
+   ```go
+   ImportStateVerifyIgnore: []string{"annotations"},
+   ```
 3. In the corresponding data source, after the resource read method, call the function `tpgresource.SetDataSourceAnnotations(d)` to make `annotations` have all of the annotations on the resource.
 
-```go
-err = resourceSecretManagerSecretRead(d, meta)
-if err != nil {
-   return err
-}
+   ```go
+   err = resourceSecretManagerSecretRead(d, meta)
+   if err != nil {
+      return err
+   }
 
-if err := tpgresource.SetDataSourceLabels(d); err != nil {
-   return err
-}
+   if err := tpgresource.SetDataSourceLabels(d); err != nil {
+      return err
+   }
 
-if err := tpgresource.SetDataSourceAnnotations(d); err != nil {
-   return err
-}
-```
+   if err := tpgresource.SetDataSourceAnnotations(d); err != nil {
+      return err
+   }
+   ```
 
 ### Handwritten resources
 

docs/content/best-practices/labels-and-annotations.md

@@ -1,4 +1,6 @@
 ---
 title: "Breaking changes"
 weight: 46
+params:
+  bookCollapseSection: true
 ---

docs/content/breaking-changes/_index.md

@@ -89,7 +89,7 @@ provider at runtime as well as in documentation.
 
 #### Field deprecation (due to removal or rename)
 
-{{< tabs "Field deprecations" >}}
+{{% tabs "Field deprecations" %}}
 {{< tab "MMv1" >}}
 Set `deprecation_message` on the field. For example:
 
@@ -124,11 +124,11 @@ The deprecation message will automatically show up in the resource documentation
    * `api_field_name` - (Optional, [Beta](https://terraform.io/docs/providers/google/guides/provider_versions.html), Deprecated) FIELD_DESCRIPTION. `api_field_name` is deprecated and will be removed in a future major release. Use `other_field_name` instead.
    ```
 {{< /tab >}}
-{{< /tabs >}}
+{{% /tabs %}}
 
 #### Resource deprecation (due to removal or rename)
 
-{{< tabs "Resource deprecations" >}}
+{{% tabs "Resource deprecations" %}}
 {{< tab "MMv1" >}}
 Set `deprecation_message` on the resource. For example:
 
@@ -165,7 +165,7 @@ The deprecation message will automatically show up in the resource documentation
    major release. Use `google_OTHER_RESOURCE_NAME` instead.
    ```
 {{< /tab >}}
-{{< /tabs >}}
+{{% /tabs %}}
 
 #### Other breaking changes