Document AnnotationsTransformer (#5247)

* Restructure existing Reference docs

Restructure Reference section for site to better match k8s.io. Change
descriptions to complete sentences. Improve instructions to locally load
site.

* Document AnnotationsTransformer on site

Dcoument AnnotationsTransformer API under Reference on site.

* Document required fields

Document required fields and explain effects of optional ones.

* Make site setup instructions more explicit

* Link required K8s fields

site/README.md

@@ -23,17 +23,28 @@ docker-compomse up -d
 ```
 
 ### hugo
-Building using the `hugo` command requires the following dependencies:
-* [hugo CLI](https://gohugo.io/getting-started/installing/)
-* [Go](https://go.dev/learn/)
-* [Node.js](https://nodejs.org/en/)
-* npm dependencies
+1. Building using the `hugo` command requires the following dependencies:
+  * [hugo CLI](https://gohugo.io/getting-started/installing/)
+  * [Go](https://go.dev/learn/)
+  * [Node.js](https://nodejs.org/en/)
+  * npm dependencies
+     ```bash
+     npm install -D autoprefixer
+     npm install -D postcss-cli
+     npm install -D postcss
+     ```
+1. Initialize [Docsy](https://www.docsy.dev/docs/) and nested [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
    ```bash
-   npm install -D autoprefixer
-   npm install -D postcss-cli
-   npm install -D postcss
+   # In Kustomize repository root directory, fetch docsy submodule at site/themes/docsy.
+   # See alternative submodule cloning options in the submodule documentation linked above.
+   git submodule init
+   git submodule update
+   # Fetch submodules nested in docsy.
+   cd site/themes/docsy
+   git submodule init
+   git submodule update
+   ```
+1. Start in development mode:
+   ```bash
+   hugo serve -D
    ```
-Start in development mode:
-```bash
-hugo serve -D
-```

site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md

@@ -0,0 +1,32 @@
+---
+title: "FieldSpec"
+linkTitle: "FieldSpec"
+weight: 1
+date: 2023-07-28
+description: >
+  FieldSpec specifies a field for Kustomize to target.
+---
+
+* **group** (string)
+
+  Kubernetes group that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all groups.
+  Currently, there is no way to specify only the core group, which is also represented by the empty string.
+
+* **version** (string)
+
+  Kubernetes version that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all versions.
+
+* **kind** (string)
+
+  Kubernetes kind that this FieldSpec applies to.
+  If empty, this FieldSpec applies to all kinds.
+
+* **path** (string)
+
+  Path to target field. Fields in path are delimited by forward slashes "/".
+
+* **create** (bool)
+
+  If true, creates fields in **path** not already present.

site/content/en/docs/Reference/API/Common Definitions/_index.md

@@ -0,0 +1,8 @@
+---
+title: "Common Definitions"
+linkTitle: "Common Definitions"
+weight: 10
+date: 2023-07-28
+description: >
+  Common definitions are fields used across the Kustomize API.
+---

site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md

@@ -0,0 +1,29 @@
+---
+title: "AnnotationsTransformer"
+linkTitle: "AnnotationsTransformer"
+weight: 1
+date: 2023-07-28
+description: >
+  AnnotationsTransformer adds annotations to user-input resources.
+---
+
+See [Transformers]({{< relref "../Transformers" >}}) for common required fields.
+
+* **apiVersion**: builtin
+* **kind**: AnnotationsTransformer
+* **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta))
+
+  Standard object's metadata.
+
+* **annotations** (map[string]string)
+
+  Map of annotations that AnnotationsTransformer will add to resources.
+
+  If not specified, AnnotationsTransformer leaves the resources unchanged.
+
+* **fieldSpecs** (\[\][FieldSpec]({{< relref "../Common%20Definitions/FieldSpec.md" >}}))
+
+  fieldSpecs specifies the field on each resource that AnnotationsTransformer should add the annotations to.
+  It essentially allows the user to re-define the field path of the Kubernetes annotations field from `metadata/annotations` for different resources.
+
+  If not specified, AnnotationsTransformer applies the annotations to the `metadata/annotations` field of all resources.

site/content/en/docs/Reference/API/Transformers/_index.md

@@ -0,0 +1,16 @@
+---
+title: "Transformers"
+linkTitle: "Transformers"
+weight: 3
+date: 2023-07-28
+description: >
+  Transformers have the ability to modify user-input resources.
+---
+
+Transformers are Kubernetes objects that dictate how Kustomize changes other Kubernetes objects that users provide.
+Besides `spec`, transformers require the same [fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/#required-fields), listed below, as other Kubernetes objects:
+
+* `apiVersion`
+* `kind`
+* `metadata`
+  * `name`

site/content/en/docs/Reference/API/_index.md

@@ -0,0 +1,11 @@
+---
+title: "API"
+linkTitle: "API"
+weight: 2
+date: 2023-07-28
+description: >
+  The Kustomize API is the set of custom resources that define its behavior.
+---
+
+This section contains user-friendly definitions of resources custom to Kustomize that define its behavior.
+Required fields are marked as such.

site/content/en/docs/Reference/kustomization_file.md → site/content/en/docs/Reference/API/kustomization_file.md

@@ -2,7 +2,7 @@
 title: "Kustomization File"
 linkTitle: "Kustomization File"
 weight: 1
-date: 2017-01-05
+date: 2023-07-28
 description: >
-  Reference for the Kustomization file
+  The Kustomization file is the entry point for Kustomize execution.
 ---

site/content/en/docs/Reference/CLI/_index.md

@@ -0,0 +1,8 @@
+---
+title: "CLI"
+linkTitle: "CLI"
+weight: 3
+date: 2023-07-28
+description: >
+  The command line tools to interact with Kustomize.
+---

site/content/en/docs/Reference/_index.md

@@ -2,13 +2,7 @@
 title: "Reference"
 linkTitle: "Reference"
 weight: 9
+date: 2023-07-28
 description: >
-  Low level reference docs for your project.
+  References are the low-level definitions in Kustomize.
 ---
-
-{{% pageinfo %}}
-This is a placeholder page that shows you how to use this template site.
-{{% /pageinfo %}}
-
-If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen,
-Javadoc, or other doc generation tools by putting them in your `static/` directory. Find out more in [Adding static content](https://docsy.dev/docs/adding-content/content/#adding-static-content). For OpenAPI reference, Docsy also provides a [Swagger UI layout and shortcode](https://www.docsy.dev/docs/adding-content/shortcodes/#swaggerui) that renders [Swagger UI](https://swagger.io/tools/swagger-ui/) using any OpenAPI YAML or JSON file as source.

site/content/en/docs/Reference/glossary.md

@@ -1,8 +1,8 @@
 ---
 title: "Glossary"
 linkTitle: "Glossary"
-weight: 3
-date: 2017-01-05
+weight: 1
+date: 2023-07-28
 description: >
-  Definitions of the terminology used when interacting with kustomize
+  Glossary defines terminology used to interact with Kustomize.
 ---