diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c788cfa5c..6fd6f09af9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -178,8 +178,8 @@ Docs are under [documentation/](documentation/). Refer to the [README.md](docume documentation contributions. -[error message style guide]: docs/style-guides/errors.md -[documentation style guide]: docs/style-guides/docs.md +[error message style guide]: architecture/style-guides/errors.md +[documentation style guide]: documentation/README.md#style-guide-for-documentation [github help]: https://help.github.com/articles/about-pull-requests/ [google's open source community guidelines]: https://opensource.google.com/conduct/ diff --git a/README.md b/README.md index f5b74fa715..bcf36e7cf3 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ The kpt toolchain includes the following components: ## Roadmap -You can read about the big upcoming features in the [roadmap doc](/docs/ROADMAP.md). +You can follow the kpt roadmap in the related [GitHub Project](https://github.com/orgs/kptdev/projects/2/views/2). ## Contributing diff --git a/docs/design-docs/00-template.md b/architecture/design-docs/00-template.md similarity index 100% rename from docs/design-docs/00-template.md rename to architecture/design-docs/00-template.md diff --git a/docs/design-docs/01-live-invenstory-to-rg.md b/architecture/design-docs/01-live-invenstory-to-rg.md similarity index 100% rename from docs/design-docs/01-live-invenstory-to-rg.md rename to architecture/design-docs/01-live-invenstory-to-rg.md diff --git a/docs/design-docs/02-oci-support.md b/architecture/design-docs/02-oci-support.md similarity index 100% rename from docs/design-docs/02-oci-support.md rename to architecture/design-docs/02-oci-support.md diff --git a/docs/design-docs/03-pipeline-merge.md b/architecture/design-docs/03-pipeline-merge.md similarity index 100% rename from docs/design-docs/03-pipeline-merge.md rename to architecture/design-docs/03-pipeline-merge.md diff --git a/docs/design-docs/04-arm-build.md b/architecture/design-docs/04-arm-build.md similarity index 100% rename from docs/design-docs/04-arm-build.md rename to architecture/design-docs/04-arm-build.md diff --git a/docs/design-docs/05-kpt-fn-exclude.md b/architecture/design-docs/05-kpt-fn-exclude.md similarity index 100% rename from docs/design-docs/05-kpt-fn-exclude.md rename to architecture/design-docs/05-kpt-fn-exclude.md diff --git a/docs/style-guides/errors.md b/architecture/style-guides/errors.md similarity index 100% rename from docs/style-guides/errors.md rename to architecture/style-guides/errors.md diff --git a/docs/sync/prototype-controller.md b/architecture/sync/prototype-controller.md similarity index 100% rename from docs/sync/prototype-controller.md rename to architecture/sync/prototype-controller.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 189220cdfb..0000000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,43 +0,0 @@ -# kpt roadmap - -Last updated: February 9th, 2023 - -Please follow the [installation](https://kpt.dev/installation/kpt-cli/) guide for installing the latest version of kpt. - -## Latest releases - -https://github.com/kptdev/kpt/releases - -## Detailed release notes -Please refer to the [release notes] page for more information about the latest features. - -## Upcoming features - -A few areas of work are ongoing. (This is not exhaustive.) - -### Explore various options for function runtime - -Currently, `kpt fn render` has dependency on docker to execute functions in pipeline. -There are performance and docker dependency issues reported by customers. We will -be exploring different function runtimes in order to address those issues. This is -just an exploratory step and actual implementation if any, will be taken up after December 2021. -[Tracking issue](https://github.com/kptdev/kpt/issues/2567). - -### Additional storage beyond Git - -Currently, `kpt pkg` workflows only support Git repositories. There is some increasing -demand from users to support other storage options beyond git(e.g., OCI). We will -be spending time understanding the use-cases and need for this project. [Tracking issue](https://github.com/kptdev/kpt/issues/2300). - -## Feedback channels: -1. File a [new issue] on Github, but please search first. - - -[new issue]: https://github.com/kptdev/kpt/issues/new/choose -[The Kpt Book]: https://kpt.dev/book/ -[apply chapter]: https://kpt.dev/book/06-apply/ -[cli-utils]: https://github.com/kubernetes-sigs/cli-utils -[function catalog]: https://catalog.kpt.dev/ -[kpt milestones]: https://github.com/kptdev/kpt/milestones -[migration guide]: https://kpt.dev/installation/migration -[release notes]: https://github.com/kptdev/kpt/releases diff --git a/docs/style-guides/docs.md b/docs/style-guides/docs.md deleted file mode 100644 index 6432eaea5f..0000000000 --- a/docs/style-guides/docs.md +++ /dev/null @@ -1,42 +0,0 @@ -# kpt Docs Style Guide - -1. CLI commands name should appear with inline quotes everywhere including in - page titles: - - Correct: `diff` - - Incorrect: `Diff` - - Incorrect: `The Diff tool` -2. Shell commands should be in `shell` code blocks and should contain exactly - one command specifing using`$`: - - ```shell - $ kpt - - ``` - -3. Links to other kpt doc pages should be absolute: - - Correct: `[pkg]: /reference/cli/pkg/get/` - - Incorrect: `[pkg]: ../../../reference/cli/pkg/get` -4. Flags must appear after positional args: - - - Correct: - - ```shell - $ kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace - ``` - - - Incorrect: - - ```shell - $ kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package - ``` - -5. The name of the tool should always appear as small caps (even at start of - sentences) and not in block quotes: - - Correct: kpt - - Incorrect: `kpt` - - Incorrect: Kpt - - Incorrect: KPT -6. References to a particular KRM group, version, kind, field should appear with - inline quotes: - - Correct: `ConfigMap` - - Incorrect: ConfigMap diff --git a/documentation/README.md b/documentation/README.md index e914e5db37..c74de4a08b 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -33,6 +33,75 @@ The site pulls some dependencies via Git submodules. If `npm install` succeeds b git submodule update --init --recursive ``` +## Style guide for documentation + +1. Use US English in the documentation + +2. Do not manually add a table of contents to the documents. Hugo and Docsy take care of this. + +3. Do not use H1 (#) headers in the documents. Docsy generates an H1 header for every document + consistent with the title of the document. Start the headings with H2 (##) + +4. Use the built-in alerts for notes and alerts + + ```go-html-template + {{%/* alert title="Note" color="primary" */%}} + This is a note. + {{%/* /alert */%}} + ``` + + ```go-html-template + {{%/* alert title="Warning" color="warning" */%}} + This is a warning. + {{%/* /alert */%}} + ``` + +5. If you add any commands to the content inline, surround the command with backticks (\` \`), like `ls -la` + +6. Do not surround IP addresses, domain names, or any other identifiers with backticks. Use italics + (\* \*) to mark any inline IP address, domain name, file name, file location, or similar. + +7. Whenever possible, define the type of code for your code blocks + - ```shell for all shell blocks + - ```golang for all Go blocks + - ```yaml for all YAML blocks + - ```yang for all YANG blocks + - a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) + + +8. Links to other kpt doc pages should be absolute: + - Correct: `[pkg]: /reference/cli/pkg/get/` + - Incorrect: `[pkg]: ../../../reference/cli/pkg/get` + +9. Flags must appear after positional args: + + - Correct: + + ```shell + $ kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace + ``` + + - Incorrect: + + ```shell + $ kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package + ``` + +10. The name of the tool should always appear as small caps (even at start of + sentences) and not in block quotes: + - Correct: kpt + - Incorrect: `kpt` + - Incorrect: Kpt + - Incorrect: KPT + +11. References to a particular KRM group, version, kind, field should appear with + inline quotes: + - Correct: `ConfigMap` + - Incorrect: ConfigMap + +12. Do not add any TBDs to the documentation. If something is missing create an [issue](https://github.com/kptdev/kpt/issues) for it + + ## License -Licensed under the [Creative Commons Attribution 4.0 International license](LICENSE-documentation) +Licensed under the [Creative Commons Attribution 4.0 International license](../LICENSE-documentation) diff --git a/documentation/content/en/faq.md b/documentation/content/en/faq.md index 4e5749f639..9aac641ccf 100644 --- a/documentation/content/en/faq.md +++ b/documentation/content/en/faq.md @@ -2,7 +2,7 @@ ### What is the roadmap for kpt? -Please visit the [roadmap document] and the [kpt milestones]. +Please visit the [roadmap GitHub Project](https://github.com/orgs/kptdev/projects/2) and the [kpt milestones]. ### How is kpt different from other solutions? @@ -131,8 +131,6 @@ don't have to alias it. It is pronounced "kept". [using functions]: /book/04-using-functions/ [contact]: /contact/ [functions catalog]: https://catalog.kpt.dev/ -[roadmap document]: - https://github.com/kptdev/kpt/blob/main/docs/ROADMAP.md [kpt milestones]: https://github.com/kptdev/kpt/milestones [kustomize solution]: https://github.com/kptdev/kpt/tree/main/package-examples/kustomize