Add API section to Reference Section #5313

bugoverdose · 2023-09-04T15:03:58Z

This PR simply migrates all the existing documentation of Kustomization fields.

I had to create new directory because there were so much content.
I tried to fix all the broken hyperlinks in the content.

k8s-ci-robot · 2023-09-04T15:04:00Z

This PR has multiple commits, and the default merge method is: merge.
You can request commits to be squashed using the label: tide/merge-method-squash

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

bugoverdose · 2023-09-04T15:04:09Z

/assign

natasha41575 · 2023-09-06T17:54:37Z

@ncapps Could you review this when you get the chance?

ncapps

Minor comments regarding links.

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

ncapps · 2023-09-08T21:16:58Z

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

+    Compose kustomizations.
+---
+
+Please check out the existing [components guide](/guides/config_management/components/) for explanation with examples. 


Suggest updating this link path to /docs/concepts/components/.

I added this content instead of referencing it because I don't think that the page will be added to our new website

9d126f6

I also added the reference to the /docs/concepts/components/ page as you suggested.

9d126f6#diff-b6a9964b549b4e0db09ed4bebe9050677517c11321bf3a4dc754aec15e319e68R20

As mentioned in this #5313 (review), because this Components page is going to eventually live under Concepts, can we remove the extra "and the components concept page"?

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

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

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

ncapps · 2023-09-08T21:34:31Z

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

+
+| Field       | Required| Description | Default |
+| -----------: | :----:| ----------- | ---- |
+| `source`| :heavy_check_mark: | The source of the value |


The :heavy_check_mark: doesn't appear to render. I am not sure if this is an issue with how Hugo is configured. This suggests we might be able to simply paste the emoji. Alternatively, we could use a different character or format to indicate that a field is required.

Maybe we should apply changes in this PR. This one's not approved but it fixes the emoji issue

replacements: change the unrendered :heavy_check_mark: for the unicode ✔️ cli-experimental#355

Nice catch! I looked into this issue briefly. I think the current approach of using the character works.

It seems that the original author tried to use Github syntax for emojis. We should be able to render characters like check marks also in html with Docsy shortcodes or Docsy's integration with Latex.

- add reference to Concept page

bugoverdose · 2023-09-14T12:04:04Z

@ncapps What do you think is the better approach.
Should we merge this PR fast and then improve each sections?
Or should we try to make this PR as perfect as possible?

ncapps · 2023-09-15T14:25:20Z

@ncapps What do you think is the better approach. Should we merge this PR fast and then improve each sections? Or should we try to make this PR as perfect as possible?

I think that we can merge this PR as is and then improve the sections as more content is added to the site.

ncapps · 2023-09-15T14:25:33Z

/lgtm

k8s-ci-robot · 2023-09-15T14:25:37Z

@ncapps: changing LGTM is restricted to collaborators

In response to this:

/lgtm

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

natasha41575 · 2023-09-15T17:36:35Z

/lgtm
/assign @annasong20

Thanks @ncapps and @bugoverdose!

Quick note on my lgtm, I didn't actually look at the PR but wanted to mark the lgtm from @ncapps above

bugoverdose · 2023-09-17T07:11:32Z

I just found out the "kustomization_file.md" file that was added from other PR.
So I (1) created a "Kustomization File" section,
(2) moved the field docs to the sub section, and
(3) fixed all the broken hyperlinks ("/docs/reference/api/" => "/docs/reference/api/kustomization-file/").

Tell me if this what you intended. @annasong20

2c444d6

annasong20

@bugoverdose Thank you for migrating the fields in the Reference section!

I didn't clarify in the excel sheet and #5279 that unlike the previous site, we want to limit the new Reference section to field syntax like #5247 and move all other descriptions, examples, etc. into Concepts. This is completely my fault and I apologize.

Therefore, we can continue with the field descriptions in the Reference section in this PR. I created a separate issue #5341 to move this content. I agree with you and @ncapps that we can take an iterative approach to the documentation. I left some minor comments to update legacy documentation. Will approve once they're addressed.

/lgtm

annasong20 · 2023-09-22T22:13:28Z

site/content/en/docs/Reference/API/Kustomization File/bases.md

@@ -0,0 +1,24 @@
+---


nit: Can we move deprecated fields into their own folder?

Since the number of deprecated fields will increase as time goes, I think we should have a really clear rule/guideline on how we should organize deprecated fields and state it somewhere before applying it.

Sure! How would you like to organize them?

Would you like to open a PR on this in a Documentation Style section on the new site? For reference, said section exists

on the current site: https://kubectl.docs.kubernetes.io/contributing/docs/

on the new site: https://kubernetes.io/docs/contribute/style/

annasong20 · 2023-09-22T22:52:39Z

site/content/en/docs/Reference/API/Kustomization File/helmCharts.md

+## Helm Chart Inflation Generator
+
+Kustomize has limited support for helm chart inflation through the `helmCharts` field.
+You can read a detailed description of this field in the docs about [kustomize builtins].


Let's link to the new site here. Also, as explained in the excel sheet, we don't want to use the confusing "builtins" terminology anymore.

Can you create a new empty "HelmChartInflationGenerator.md" under the Transformers directory to link on this page? We can replace "kustomize builtins" with "HelmChartInflationGenerator".

annasong20 · 2023-09-22T22:56:10Z

site/content/en/docs/Reference/API/Kustomization File/helmCharts.md

+    Helm chart inflation generator.
+---
+
+[kustomize builtins]: https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_helmchartinflationgenerator_


The new link suggested in the previous comment would live here.

annasong20 · 2023-09-22T22:58:30Z

site/content/en/docs/Reference/API/Kustomization File/components.md

+title: "Components"
+linkTitle: "Components"


nit: Can we use lower case "components" here to match the other fields?

annasong20 · 2023-09-23T04:33:14Z

site/content/en/docs/Reference/API/Kustomization File/vars.md

+particular objects as specified by kustomize's
+configuration data.
+
+The default config data for vars is at [/api/konfig/builtinpluginconsts/varreference.go](https://github.com/kubernetes-sigs/kustomize/blob/master/api/konfig/builtinpluginconsts/varreference.go)


Can we replace this broken link with https://github.com/kubernetes-sigs/kustomize/blob/kustomize/v5.1.1/api/konfig/builtinpluginconsts/varreference.go

We recently moved the location of these constants. This new link also references a specific branch instead of master, so technically it should never break.

k8s-ci-robot · 2023-09-23T05:50:04Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: annasong20, bugoverdose

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [annasong20]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

annasong20 · 2023-09-23T06:05:38Z

@bugoverdose The "approve" in my last comment must have triggered an actual approval... My comments weren't major. You can address them in a follow-up PR.

k8s-ci-robot requested review from annasong20 and yuwenma September 4, 2023 15:04

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Sep 4, 2023

k8s-ci-robot assigned bugoverdose Sep 4, 2023

k8s-ci-robot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Sep 4, 2023

ncapps reviewed Sep 8, 2023

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 9, 2023

bugoverdose mentioned this pull request Sep 11, 2023

doc(kustomize/replacements): add select and reject explanation kubernetes-sigs/cli-experimental#360

Closed

bugoverdose added 3 commits September 14, 2023 12:40

docs: setup API section with cli-experimental site

e19ca54

docs(api): fix broken hyperlinks

5c1a022

docs(api/replacements): fix heavy check mark issue

bd8045b

bugoverdose force-pushed the docs/api branch from 8788346 to bd8045b Compare September 14, 2023 03:44

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 14, 2023

bugoverdose added 4 commits September 14, 2023 12:55

docs(api/components): add Components guide from cli-experimental

9d126f6

- add reference to Concept page

docs(api): fix broken links

a2b60e4

docs(api/generatorOptions): fill up empty links

ae041b5

docs(api/patches): fix broken links

d30e457

k8s-ci-robot assigned annasong20 and natasha41575 Sep 15, 2023

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 15, 2023

natasha41575 unassigned natasha41575 and bugoverdose Sep 15, 2023

docs(api/kustomizaion-file): migrate field sections

2c444d6

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 17, 2023

annasong20 suggested changes Sep 23, 2023

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 23, 2023

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Sep 23, 2023

k8s-ci-robot merged commit af781bf into kubernetes-sigs:master Sep 23, 2023
9 checks passed

annasong20 mentioned this pull request Oct 3, 2023

Add Tasks Documentation #5346

Closed

ncapps mentioned this pull request Nov 13, 2023

REQUEST: New membership for @ncapps kubernetes/org#4583

Closed

9 tasks

ncapps mentioned this pull request Dec 1, 2023

Add ncapps to reviewers #5469

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add API section to Reference Section #5313

Add API section to Reference Section #5313

bugoverdose commented Sep 4, 2023

k8s-ci-robot commented Sep 4, 2023

bugoverdose commented Sep 4, 2023

natasha41575 commented Sep 6, 2023

ncapps left a comment

ncapps Sep 8, 2023

bugoverdose Sep 14, 2023

annasong20 Sep 23, 2023

ncapps Sep 8, 2023

bugoverdose Sep 11, 2023

bugoverdose Sep 14, 2023

annasong20 Sep 23, 2023

bugoverdose commented Sep 14, 2023

ncapps commented Sep 15, 2023

ncapps commented Sep 15, 2023

k8s-ci-robot commented Sep 15, 2023

natasha41575 commented Sep 15, 2023 •

edited

bugoverdose commented Sep 17, 2023 •

edited

annasong20 left a comment

annasong20 Sep 22, 2023

bugoverdose Sep 24, 2023 •

edited

annasong20 Sep 25, 2023

annasong20 Sep 22, 2023

annasong20 Sep 22, 2023

annasong20 Sep 22, 2023

annasong20 Sep 23, 2023

k8s-ci-robot commented Sep 23, 2023

annasong20 commented Sep 23, 2023

		title: "Components"
		linkTitle: "Components"

Add API section to Reference Section #5313

Add API section to Reference Section #5313

Conversation

bugoverdose commented Sep 4, 2023

k8s-ci-robot commented Sep 4, 2023

bugoverdose commented Sep 4, 2023

natasha41575 commented Sep 6, 2023

ncapps left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bugoverdose commented Sep 14, 2023

ncapps commented Sep 15, 2023

ncapps commented Sep 15, 2023

k8s-ci-robot commented Sep 15, 2023

natasha41575 commented Sep 15, 2023 • edited

bugoverdose commented Sep 17, 2023 • edited

annasong20 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bugoverdose Sep 24, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

k8s-ci-robot commented Sep 23, 2023

annasong20 commented Sep 23, 2023

natasha41575 commented Sep 15, 2023 •

edited

bugoverdose commented Sep 17, 2023 •

edited

bugoverdose Sep 24, 2023 •

edited