Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -234,7 +234,7 @@ git config --global user.name "Your Name"

### Module Generation

If changes modify CLI documentation in documentation/content/en/reference/cli/:
If changes modify CLI documentation in documentation/content/en/documentation/6-references/cli/:

* Run `make generate` to regenerate `internal/docs/generated/`
* Commit generated files
Expand Down Expand Up @@ -274,7 +274,7 @@ If changes modify CLI documentation in documentation/content/en/reference/cli/:

## Implementation Notes for Code Changes

* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/content/en/reference/cli/` for documentation
* **CLI Commands**: Add to `commands/` directory; use Cobra; update `documentation/content/en/documentation/6-references/cli/` for documentation
* **Library Code**: Place in `pkg/` for public APIs; use `internal/` for internal utilities
* **Tests**: Colocate `*_test.go` files with source; use testdata directories for fixtures
* **Generated Code**: Run `make generate` after modifying templates
Expand Down
14 changes: 7 additions & 7 deletions cli/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,13 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//go:generate mdtogo ../documentation/content/en/reference/cli/live ../internal/docs/generated/livedocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/reference/cli/pkg ../internal/docs/generated/pkgdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/reference/cli/fn ../internal/docs/generated/fndocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/reference/cli/alpha ../internal/docs/generated/alphadocs --license=none --strategy=cmdDocs --recursive=false
//go:generate mdtogo ../documentation/content/en/reference/cli/alpha/sync ../internal/docs/generated/syncdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/reference/cli/alpha/wasm ../internal/docs/generated/wasmdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/reference/cli/_index.md ../internal/docs/generated/overview --license=none --strategy=cmdDocs
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/live ../internal/docs/generated/livedocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/pkg ../internal/docs/generated/pkgdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/fn ../internal/docs/generated/fndocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/alpha ../internal/docs/generated/alphadocs --license=none --strategy=cmdDocs --recursive=false
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/alpha/sync ../internal/docs/generated/syncdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/alpha/wasm ../internal/docs/generated/wasmdocs --license=none --strategy=cmdDocs --recursive=true
//go:generate mdtogo ../documentation/content/en/documentation/6-references/cli/_index.md ../internal/docs/generated/overview --license=none --strategy=cmdDocs
package main

import (
Expand Down
4 changes: 2 additions & 2 deletions documentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,8 @@ The token is only sent to github.com domains.


8. Links to other kpt doc pages should be absolute:
- Correct: `[pkg]: /reference/cli/pkg/get/`
- Incorrect: `[pkg]: ../../../reference/cli/pkg/get`
- Correct: `[pkg]: /documentation/6-references/cli/pkg/get/`
- Incorrect: `[pkg]: ../../../documentation/6-references/cli/pkg/get`

9. Flags must appear after positional args:

Expand Down
3 changes: 2 additions & 1 deletion documentation/assets/scss/_sidebar-left.scss
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,8 @@
&::after {
display: inline-flex;
content: '\f078';
font-family: 'Font Awesome 5 Free';
font-family: $td-font-awesome-font-name;
font-weight: 900;
}
}
&.active-path {
Expand Down
2 changes: 1 addition & 1 deletion documentation/content/en/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ kpt is an open source project and anyone can [contribute](https://github.com/kpt
# For users

To get familiar with kpt, the best way to start is with the first 4 chapters of the kpt [Book]({{% relref "book" %}}).
Furthermore it is useful to check the [references]({{% relref "reference" %}}) and the catalog of [selected krm functions](https://catalog.kpt.dev).
Furthermore it is useful to check the [references]({{ with or (site.GetPage "/documentation/6-references") (site.GetPage "/reference") }}{{ .RelPermalink }}{{ end }}) and the catalog of [selected krm functions](https://catalog.kpt.dev).

Use our [public Dosu space](https://app.dosu.dev/b19fb34f-d249-48ae-a3b1-2bd8ec156e41/ask) to ask anything about kpt.

Expand Down
4 changes: 2 additions & 2 deletions documentation/content/en/book/01-getting-started/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Follow the [instructions](https://podman.io/getting-started/installation) to ins
If you want to set up a rootless container runtime, then [this](https://rootlesscontaine.rs/) may be a useful resource for you.

Environment variables can be used to control which container runtime to use. More details can be found in the reference
documents for [`kpt fn render`]({{% relref "/reference/cli/fn/render" %}}) and [`kpt fn eval`]({{% relref "/reference/cli/fn/eval" %}}).
documents for [`kpt fn render`]({{% relref "/documentation/6-references/cli/fn/render" %}}) and [`kpt fn eval`]({{% relref "/documentation/6-references/cli/fn/eval" %}}).

### Kubernetes cluster

Expand Down Expand Up @@ -105,7 +105,7 @@ vim deployment.yaml

#### Automating one-time edits with functions

The [`kpt fn`]({{% relref "/reference/cli/fn" %}}) set of commands enables you to execute programs called _kpt functions_. These programs are
The [`kpt fn`]({{% relref "/documentation/6-references/cli/fn" %}}) set of commands enables you to execute programs called _kpt functions_. These programs are
packaged as containers and take YAML files as input, mutate or validate them, and then output YAML.

For example, you can use a function (`ghcr.io/kptdev/krm-functions-catalog/search-replace:latest`) to search for and replace all the occurrences of the `app` key, in the `spec` section of the YAML document (`spec.**.app`), and set the value to `my-nginx`.
Expand Down
4 changes: 2 additions & 2 deletions documentation/content/en/book/02-concepts/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ This enables machine manipulation of configuration for Kubernetes and any infras

The kpt toolchain includes the following components:

- [**kpt CLI**]({{% relref "/reference/cli" %}}): The kpt CLI supports package and function operations, and also deployment, via
- [**kpt CLI**]({{% relref "/documentation/6-references/cli" %}}): The kpt CLI supports package and function operations, and also deployment, via
either direct apply or GitOps. By keeping an inventory of deployed resources, kpt enables resource pruning, aggregated
status and observability, and an improved preview experience.

Expand Down Expand Up @@ -206,7 +206,7 @@ When you deploy the package with `kpt live apply`, local configuration resources
are automatically filtered out. They exist in the package solely to support the
pipeline. See [Chapter 4]({{% relref "/book/04-using-functions" %}}) for how function configs use
this annotation, and the
[`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}) for
[`local-config` annotation reference]({{% relref "/documentation/6-references/annotations/local-config" %}}) for
full details.

## Workflows
Expand Down
16 changes: 8 additions & 8 deletions documentation/content/en/book/03-packages/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ kpt pkg get https://github.com/kptdev/kpt.git/package-examples/wordpress@v1.0.0-

A package in a Git repository can be fetched by specifying a branch, tag, or commit SHA. In the above example, the tag `v1.0.0-beta.61` is specified.

See the [get command reference]({{% relref "/reference/cli/pkg/get" %}}) for usage.
See the [get command reference]({{% relref "/documentation/6-references/cli/pkg/get" %}}) for usage.

The `Kptfile` contains the metadata about the origin of the forked package. Have a look at the content of the `Kptfile` on
your local filesystem:
Expand Down Expand Up @@ -202,7 +202,7 @@ Package "wordpress" (independent)
└── [service.yaml] Service wordpress-mysql
```

See the [tree command reference]({{% relref "/reference/cli/pkg/tree" %}}) for usage.
See the [tree command reference]({{% relref "/documentation/6-references/cli/pkg/tree" %}}) for usage.

In addition, you can use a kpt function, such as `search-replace`, to run a query on the package. For example, to search for resources that have a field with the
`spec.selector.tier` path, use the following kpt function:
Expand All @@ -224,7 +224,7 @@ Every file in a package falls into one of three categories:
`.json` file, or a file named `Kptfile`) but aren't actually valid KRM resources, such as a Helm
`values.yaml`. kpt doesn't know what to do with these, so they must be excluded one way or another,
either manually via `.krmignore` or automatically via the
[`kpt.dev/auto-ignore-non-krm`]({{% relref "/reference/annotations/auto-ignore-non-krm" %}}) annotation
[`kpt.dev/auto-ignore-non-krm`]({{% relref "/documentation/6-references/annotations/auto-ignore-non-krm" %}}) annotation
described below. Like `.krmignore`, the annotation is scoped per package: a subpackage with its own
`Kptfile` does not inherit it from a parent package.

Expand All @@ -251,9 +251,9 @@ If a package contains a non-KRM file (category 3 above) that isn't excluded by `
listed above fail before doing any work, listing every such file found across the whole package tree in
one error. This applies to files that parse as YAML but aren't valid KRM; a file that isn't valid YAML at
all fails differently and isn't covered by this consolidated reporting or by the annotation below -- see
["Malformed YAML is different, and isn't covered"]({{% relref "/reference/annotations/auto-ignore-non-krm#malformed-yaml-is-different-and-isnt-covered" %}})
["Malformed YAML is different, and isn't covered"]({{% relref "/documentation/6-references/annotations/auto-ignore-non-krm#malformed-yaml-is-different-and-isnt-covered" %}})
for details. If you'd rather non-KRM files be skipped automatically instead of maintaining a `.krmignore`
list by hand, see the [`kpt.dev/auto-ignore-non-krm`]({{% relref "/reference/annotations/auto-ignore-non-krm" %}})
list by hand, see the [`kpt.dev/auto-ignore-non-krm`]({{% relref "/documentation/6-references/annotations/auto-ignore-non-krm" %}})
annotation.

## Editing a package
Expand Down Expand Up @@ -310,7 +310,7 @@ Regardless of how you have edited the package, you need to _render_ it. Use the
kpt fn render wordpress
```

See the [render command reference]({{% relref "/reference/cli/fn/render" %}}) for command usage.
See the [render command reference]({{% relref "/documentation/6-references/cli/fn/render" %}}) for command usage.

`render` is a critical step in the package lifecycle. At a high level, it performs the following steps:

Expand Down Expand Up @@ -379,7 +379,7 @@ The `update` command updates the local `wordpress` package and the dependent `my

Several different strategies are available for handling the merge. By default, the `resource-merge` strategy is used. This performs a structural comparison of the resource using the OpenAPI schema.

See the [update command reference]({{% relref "/reference/cli/pkg/update" %}}) for usage.
See the [update command reference]({{% relref "/documentation/6-references/cli/pkg/update" %}}) for usage.

### Committing the updated resources

Expand All @@ -398,7 +398,7 @@ kpt pkg init awesomeapp

This command automatically creates the `awesomeapp` directory, if it does not already exist, eliminating the need to manually create the directory beforehand.

See the [init command reference]({{% relref "/reference/cli/pkg/init" %}}) for usage.
See the [init command reference]({{% relref "/documentation/6-references/cli/pkg/init" %}}) for usage.

The `info` section of the `Kptfile` contains some optional package metadata that you may want to set. These fields are not consumed by any functionality in kpt:

Expand Down
10 changes: 5 additions & 5 deletions documentation/content/en/book/04-using-functions/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Package "wordpress":
Successfully executed 3 function(s) in 2 package(s).
```

See the [render command reference]({{% relref "/reference/cli/fn/render" %}}) for usage.
See the [render command reference]({{% relref "/documentation/6-references/cli/fn/render" %}}) for usage.

When you invoke the `render` command, kpt performs the following steps:

Expand Down Expand Up @@ -408,7 +408,7 @@ This annotation is useful for:
- Any resource that should exist in the package but not on the cluster

For full details on the annotation schema and behavior, see the
[`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}).
[`local-config` annotation reference]({{% relref "/documentation/6-references/annotations/local-config" %}}).

### Specifying function `name`

Expand Down Expand Up @@ -879,7 +879,7 @@ Alternatively, for convenience, you can use the short-hand form of the above com
kpt fn eval wordpress -i set-namespace:latest -- namespace=mywordpress
```

See the [eval command reference]({{% relref "/reference/cli/fn/eval" %}}) for usage.
See the [eval command reference]({{% relref "/documentation/6-references/cli/fn/eval" %}}) for usage.

This changes the resources in the `wordpress` package and the `mysql` subpackage.

Expand Down Expand Up @@ -1042,8 +1042,8 @@ kpt fn source wordpress \
| kpt fn sink my-wordpress
```

See the command reference for usage of the [source]({{% relref "/reference/cli/fn/source" %}}) command and the
[sink]({{% relref "/reference/cli/fn/sink" %}}) command.
See the command reference for usage of the [source]({{% relref "/documentation/6-references/cli/fn/source" %}}) command and the
[sink]({{% relref "/documentation/6-references/cli/fn/sink" %}}) command.

The above pipeline can be described as follows:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ When kpt reads resources from disk, each resource in the `ResourceList` carries
`internal.config.kubernetes.io/path` annotation indicating its file path relative to
the package directory. When a function creates new resources, it should set this
annotation to a path relative to the same package directory. See the
[annotations reference]({{% relref "/reference/annotations#path-annotation-details" %}})
[annotations reference]({{% relref "/documentation/6-references/annotations#path-annotation-details" %}})
for full details.

As an example, you can see the `ResourceList` containing resources in the
Expand Down
14 changes: 7 additions & 7 deletions documentation/content/en/book/06-deploying-packages/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ number of pods have been created and become available.

For core kubernetes types, reconcile status is computed using hardcoded rules.
For CRDs, the status computation is based on the recommended
[convention for status fields]({{% relref "/reference/schema/crd-status-convention" %}})
[convention for status fields]({{% relref "/documentation/6-references/schema/crd-status-convention" %}})
that must be followed by custom resource publishers. If CRDs follow
these conventions, `kpt live apply` will correctly compute the reconciliation status.

Expand Down Expand Up @@ -117,7 +117,7 @@ uses heuristics to automatically choose the namespace. In this example, all the
resources in `wordpress` package are in the `default` namespace, so it chooses
`default` for the namespace. Alternatively, you can manually configure the name
and namespace of the `ResourceGroup` resource. Refer to the
[init command reference]({{% relref "/reference/cli/live/init" %}}) for usage.
[init command reference]({{% relref "/documentation/6-references/cli/live/init" %}}) for usage.

{{% alert title="Warning" color="warning" %}}
Once a package is applied to the cluster, do not change the `ResourceGroup` CR. Doing so corrupts the association between the package and the inventory in the cluster, possibly leading to unpredictable and destructive operations.
Expand All @@ -131,7 +131,7 @@ Note that not all resources in the package are applied to the cluster. Resources
annotated with `config.kubernetes.io/local-config: "true"` are automatically
filtered out. These are typically function configs or helper resources used only
during rendering. The `Kptfile` itself is also excluded. For more details, see
the [`local-config` annotation reference]({{% relref "/reference/annotations/local-config" %}}).
the [`local-config` annotation reference]({{% relref "/documentation/6-references/annotations/local-config" %}}).

The `wordpress` package requires a `Secret` containing the mysql password.
Let's create that first:
Expand Down Expand Up @@ -170,7 +170,7 @@ deployment.apps/wordpress reconciled
6 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

Refer to the [apply command reference]({{% relref "/reference/cli/live/apply" %}}) for usage.
Refer to the [apply command reference]({{% relref "/documentation/6-references/cli/live/apply" %}}) for usage.

### `ResourceGroup` CRD

Expand Down Expand Up @@ -233,7 +233,7 @@ persistentvolumeclaim/mysql-pv-claim is Current: PVC is Bound
persistentvolumeclaim/wp-pv-claim is Current: PVC is Bound
```

Refer to the [status command reference]({{% relref "/reference/cli/live/status" %}}) for usage.
Refer to the [status command reference]({{% relref "/documentation/6-references/cli/live/status" %}}) for usage.

### Delete the package

Expand Down Expand Up @@ -264,7 +264,7 @@ persistentvolumeclaim/wp-pv-claim reconciled
6 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

Refer to the [destroy command reference]({{% relref "/reference/cli/live/destroy" %}}) for usage.
Refer to the [destroy command reference]({{% relref "/documentation/6-references/cli/live/destroy" %}}) for usage.

## Handling Dependencies

Expand Down Expand Up @@ -353,4 +353,4 @@ service/wordpress-mysql reconciled
4 resource(s) reconciled, 0 skipped, 0 failed to reconcile, 0 timed out
```

See [depends-on]({{% relref "/reference/annotations/depends-on" %}}) for more information.
See [depends-on]({{% relref "/documentation/6-references/annotations/depends-on" %}}) for more information.
2 changes: 1 addition & 1 deletion documentation/content/en/book/08-ci-user-guide/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ It is important to distinguish `kpt fn render` from `kpt fn eval`:
## Applying configuration in CI (optional and gated)

Applying configuration from CI should be treated as optional and tightly controlled to prevent accidental cluster
changes. In most pipelines, [kpt live apply]({{% relref "/reference/cli/live/apply" %}}) runs only when a deployment is explicitly
changes. In most pipelines, [kpt live apply]({{% relref "/documentation/6-references/cli/live/apply" %}}) runs only when a deployment is explicitly
authorized.

Run apply only under these conditions:
Expand Down
8 changes: 8 additions & 0 deletions documentation/content/en/documentation/1-overview/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Overview"
weight: -1
description: >
kpt overview
---

Chapter 2 Concepts / What is kpt
8 changes: 8 additions & 0 deletions documentation/content/en/documentation/2-concepts/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Concepts"
weight: 2
description: >
kpt concepts
---

Chapter 2 Concepts
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Functions"
weight: 3
description: >
kpt functions
---

Chapter 2 Concepts / Functions
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Packages"
weight: 1
description: >
kpt packages
---

Chapter 2 Concepts / Packages
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Workflows"
weight: 2
description: >
kpt workflows
---

Chapter 2 Concepts / Workflows
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Installation"
weight: 3
description: >
kpt installation
---

Chapter 3 Installation
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Docker"
weight: 2
description: >
kpt Docker installation
---

Installation / Docker
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Homebrew"
weight: 1
description: >
kpt Homebrew installation
---

Installation / Homebrew
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Source"
weight: 3
description: >
kpt source installation
---

Installation / Source
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Getting Started"
weight: 4
description: >
kpt getting started
---

Chapter 4 Getting Started
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "Quickstart"
weight: 2
description: >
kpt quickstart
---

Chapter 1 Getting started / Quickstart
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: "System Requirements"
weight: 1
description: >
kpt system requirements
---

Chapter 1 Getting started / System requirements
Loading
Loading