diff --git a/code-samples/community/README.md b/code-samples/community/README.md deleted file mode 100644 index 91dafdb8a..000000000 --- a/code-samples/community/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# Community code samples - -Get up and running with one of the community code samples. These samples are -contributed and maintained by members of the Knative community. - -**Note:** These samples might become outdated or the original author might be unable to maintain their contribution. If you find that something isn't working, lend a helping hand and fix it in a PR. - -[Learn more about the lifespan of samples](https://github.com/knative/docs/blob/main/contribute-to-docs/what-to-contribute/creating-code-samples.md#user-focused-content) - -[**Browse more Knative code samples**](..) - -## Interactive Serving sample - -Check out this [Katacoda tutorial](https://www.katacoda.com/swapb/scenarios/knative-intro) -which guides you through installing Knative and the `kn` command line tool, deploying a -sample container, updating your deployment, and performing a traffic split -between the two versions. - -## Serving samples - -Knative Serving sample apps. - -| Sample Name | Description | Language(s) | -| ----------- | ----------- | ----------- | -| Hello World | A quick introduction to Knative Serving that highlights how to deploy an app. | [Clojure](serving/helloworld-clojure/), [Dart](serving/helloworld-dart/), [Elixir](serving/helloworld-elixir/), [Haskell](serving/helloworld-haskell/), [Java - Micronaut](serving/helloworld-java-micronaut/), [Java - Quarkus](serving/helloworld-java-quarkus/), [R - Go Server](serving/helloworld-r/), [Rust](serving/helloworld-rust/), [Swift](serving/helloworld-swift/), [Vertx](serving/helloworld-vertx/) | -| Machine Learning | A quick introduction to using Knative Serving to serve machine learning models | [Python - BentoML](serving/machinelearning-python-bentoml) - -### Eventing and Eventing Resources samples - -_Be the first to contribute an Eventing or Eventing Sources code sample to the -community collection._ - -## Client samples - -Knative `kn` Client sample workflows and apps. - -| Sample Name | Description | -| ----------- | ----------- | -| [knfun](https://github.com/maximilien/knfun) | Knative micro-functions (Twitter and Watson APIs) demo using the `kn` client. | diff --git a/config/nav.yml b/config/nav.yml index 02acb489a..a83dc6551 100644 --- a/config/nav.yml +++ b/config/nav.yml @@ -129,6 +129,9 @@ nav: # Serving - troubleshooting - Troubleshooting: - Debugging application issues: serving/troubleshooting/debugging-application-issues.md + # Serving reference docs + - Reference: + - Serving API: serving/reference/serving-api.md ############################################################################### # Eventing ############################################################################### @@ -219,6 +222,9 @@ nav: - KReference.Group field: eventing/experimental-features/kreference-group.md - Knative reference mapping: eventing/experimental-features/kreference-mapping.md - Strict Subscriber: eventing/experimental-features/strict-subscriber.md + # Eventing reference docs + - Reference: + - Eventing API: eventing/reference/eventing-api.md ############################################################################### # CLI ############################################################################### @@ -236,11 +242,6 @@ nav: - Eventing code samples: samples/eventing.md # Reference docs - Reference: - - Reference overview: reference/README.md - - API: - - Serving: reference/api/serving-api.md - - Eventing: reference/api/eventing-api.md - - Client: reference/client/README.md - Concepts: - Duck types: reference/concepts/duck-typing.md - Security: reference/security/README.md diff --git a/config/redirects.yml b/config/redirects.yml index cfea29573..0cbeb9137 100644 --- a/config/redirects.yml +++ b/config/redirects.yml @@ -1,9 +1,12 @@ plugins: redirects: redirect_maps: - community/contributing.md : contributing/contributing.md - community/about.md : contributing/about.md - community/README.md : contributing/README.md + reference/client/README.md: client/README.md + reference/api/eventing-api.md: eventing/reference/eventing-api.md + reference/api/serving-api.md: serving/reference/serving-api.md + community/contributing.md: contributing/contributing.md + community/about.md: contributing/about.md + community/README.md: contributing/README.md eventing/getting-started.md: getting-started/getting-started-eventing.md admin/collecting-logs/README.md: serving/observability/logging/collecting-logs.md admin/collecting-metrics/README.md: serving/observability/metrics/collecting-metrics.md diff --git a/contribute-to-docs/what-to-contribute/creating-code-samples.md b/contribute-to-docs/what-to-contribute/creating-code-samples.md index 54c54da1c..8d4d967da 100644 --- a/contribute-to-docs/what-to-contribute/creating-code-samples.md +++ b/contribute-to-docs/what-to-contribute/creating-code-samples.md @@ -47,9 +47,7 @@ either internal contributor content, or external-facing user content. set of samples. - **Community owned and maintained samples**: For sample code which doesn't - meet the mentioned criteria, put the code in a separate repository and link to - it [from this page](https://github.com/knative/docs/tree/main/code-samples/community/README.md). - These samples might not receive regular maintenance. It is possible that a + meet the mentioned criteria, put the code in a separate repository and link to it [from this page](../../docs/samples/README.md). These samples might not receive regular maintenance. It is possible that a sample is no longer current and is not actively maintained by its original author. While we encourage a contributor to maintain their content, we acknowledge that it's not always possible for certain reasons, for example diff --git a/docs/client/README.md b/docs/client/README.md index 48efa64f0..98d8c4bbf 100755 --- a/docs/client/README.md +++ b/docs/client/README.md @@ -17,6 +17,10 @@ See [Install and Set Up `kubectl`](https://kubernetes.io/docs/tasks/tools/instal See [Installing `kn`](install-kn.md). +### kn reference documentation + +See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in Github. + ## Connecting CLI tools to your cluster After you have installed `kubectl` or `kn`, these tools will search for the `kubeconfig` file of your cluster in the default location of `$HOME/.kube/config`, and will use this file to connect to the cluster. A `kubeconfig` file is usually automatically created when you create a Kubernetes cluster. diff --git a/docs/eventing/event-registry.md b/docs/eventing/event-registry.md index e42bd06a5..c04b735e4 100644 --- a/docs/eventing/event-registry.md +++ b/docs/eventing/event-registry.md @@ -52,7 +52,7 @@ status: ``` For the full specification for an EventType object, see the -[EventType API reference](../reference/api/eventing-api.md#eventing.knative.dev/v1beta1.EventType). +[EventType API reference](../eventing/reference/eventing-api.md#eventing.knative.dev/v1beta1.EventType). The `metadata.name` field is advisory, that is, non-authoritative. It is typically generated using `generateName` to avoid naming collisions. diff --git a/docs/reference/api/eventing-api.md b/docs/eventing/reference/eventing-api.md similarity index 100% rename from docs/reference/api/eventing-api.md rename to docs/eventing/reference/eventing-api.md diff --git a/docs/reference/README.md b/docs/reference/README.md deleted file mode 100644 index 3206ad902..000000000 --- a/docs/reference/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Knative Reference Documentation - -Knative reference documentation. diff --git a/docs/reference/client/README.md b/docs/reference/client/README.md deleted file mode 100644 index 52f158293..000000000 --- a/docs/reference/client/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Knative Client Reference - -See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in Github. diff --git a/docs/samples/README.md b/docs/samples/README.md index b6c238f62..51381dfd3 100755 --- a/docs/samples/README.md +++ b/docs/samples/README.md @@ -1,32 +1,42 @@ # Knative code samples -Find and use Knative code samples to help you get up and running with common use -cases. Code samples include content from the Knative team and community members. +You can use Knative code samples to help you get up and running with common use +cases. -Browse all code samples to find other languages and use cases that might align -closer with your goals. +## Knative owned samples -### Knative owned and maintained - -View the set of Knative code samples that are actively tested and maintained: +Knative code samples that are actively tested and maintained by Knative working groups: - [Eventing and Eventing Sources code samples](eventing.md) - [Serving code samples](serving.md) -### Community owned and maintained +## Community owned samples -[View code samples that are contributed and maintained by the community](https://github.com/knative/docs/tree/main/code-samples/community). +Get up and running with one of the community code samples. These samples are +contributed and maintained by members of the Knative community. [View code samples that are contributed and maintained by the community](https://github.com/knative/docs/tree/main/code-samples/community). -### External code samples +**Note:** These samples might become outdated or the original author might be unable to maintain their contribution. If you find that something isn't working, lend a helping hand and fix it in a PR. + +[Learn more about the lifespan of samples](https://github.com/knative/docs/blob/main/contribute-to-docs/what-to-contribute/creating-code-samples.md#user-focused-content) + +| Sample Name | Description | Language(s) | +| ----------- | ----------- | ----------- | +| Hello World | A quick introduction to Knative Serving that highlights how to deploy an app. | [Clojure](serving/helloworld-clojure/), [Dart](serving/helloworld-dart/), [Elixir](serving/helloworld-elixir/), [Haskell](serving/helloworld-haskell/), [Java - Micronaut](serving/helloworld-java-micronaut/), [Java - Quarkus](serving/helloworld-java-quarkus/), [R - Go Server](serving/helloworld-r/), [Rust](serving/helloworld-rust/), [Swift](serving/helloworld-swift/), [Vertx](serving/helloworld-vertx/) | +| Machine Learning | A quick introduction to using Knative Serving to serve machine learning models | [Python - BentoML](serving/machinelearning-python-bentoml) + +## External code samples A list of links to Knative code samples located outside of Knative repos: -- [Image processing using Knative Eventing, Cloud Run on GKE (Knative Serving implementation) and Google Cloud Vision API](https://github.com/akashrv/knative-samples/blob/master/docs/image-processing.md) -- [A potpourri of Knative Eventing Examples](https://github.com/lionelvillard/knative-examples) -- [Knfun - a complete Knative example of three functions using Twitter and Watson API that use kn to deploy and manage functions](https://github.com/maximilien/knfun) -- [Knative Eventing (Cloud Events) example using spring-boot and spring-cloud-streams + Kafka](https://salaboy.com/2020/02/20/getting-started-with-knative-2020/) -- [Image processing pipeline using Knative Eventing on GKE, Google Cloud Vision API and ImageSharp library](https://github.com/meteatamel/knative-tutorial/blob/master/docs/image-processing-pipeline.md) -- [BigQuery processing pipeline using Knative Eventing on GKE, Cloud Scheduler, BigQuery, mathplotlib and SendGrid](https://github.com/meteatamel/knative-tutorial/blob/master/docs/bigquery-processing-pipeline.md) -- [Performance testing with SLO validation](/blog/articles/performance-test-with-slos/) + -_Please add links to your externally hosted Knative code sample._ +- [Image processing using Knative Eventing, Cloud Run on GKE and Google Cloud Vision API](https://github.com/akashrv/knative-samples/blob/master/docs/image-processing.md) +- [Knative Eventing Examples](https://github.com/lionelvillard/knative-examples) +- [knfun](https://github.com/maximilien/knfun) +- [Getting Started with Knative 2020](https://salaboy.com/2020/02/20/getting-started-with-knative-2020/) +- [Image Processing Pipeline](https://github.com/meteatamel/knative-tutorial/blob/master/docs/image-processing-pipeline.md) +- [BigQuery Processing Pipeline](https://github.com/meteatamel/knative-tutorial/blob/master/docs/bigquery-processing-pipeline.md) +- [Simple Performance Testing with SLOs](/blog/articles/performance-test-with-slos/) + +!!! tip + Add a link here to your externally hosted Knative code sample. diff --git a/docs/serving/load-balancing/target-burst-capacity.md b/docs/serving/load-balancing/target-burst-capacity.md index 488bcdbb6..0ed00a92b 100644 --- a/docs/serving/load-balancing/target-burst-capacity.md +++ b/docs/serving/load-balancing/target-burst-capacity.md @@ -61,7 +61,7 @@ Target burst capacity can be configured using a combination of the following par !!! note Ingress gateway load balancing requires additional configuration. For more information about load balancing using an ingress - gateway, see the [Serving API](../../reference/api/serving-api.md) documentation. + gateway, see the [Serving API](../../serving/reference/serving-api.md) documentation. - If `autoscaling.knative.dev/target-burst-capacity` is set to `0`, the Activator is only added to the request path during scale from zero scenarios, and ingress load balancing will be applied. diff --git a/docs/reference/api/serving-api.md b/docs/serving/reference/serving-api.md similarity index 100% rename from docs/reference/api/serving-api.md rename to docs/serving/reference/serving-api.md diff --git a/hack/build.sh b/hack/build.sh index ecfbf0c40..be0922bb3 100755 --- a/hack/build.sh +++ b/hack/build.sh @@ -46,14 +46,21 @@ if [ "$BUILD_VERSIONS" == "no" ]; then else # Versioning: pre-release (HEAD): docs => development/ cp -r . $TEMP/docs-main - curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/main/docs/serving-api.md -s > "$TEMP/docs-main/docs/reference/api/serving-api.md" - curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/main/docs/eventing-api.md -s > "$TEMP/docs-main/docs/reference/api/eventing-api.md" + curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/main/docs/serving-api.md -s > "$TEMP/docs-main/docs/serving/reference/serving-api.md" + curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/main/docs/eventing-api.md -s > "$TEMP/docs-main/docs/eventing/reference/eventing-api.md" pushd "$TEMP/docs-main"; mkdocs build -f mkdocs.yml -d $SITE/development; popd # Latest release branch to /docs git clone --depth 1 -b ${DOCS_BRANCHES[0]} https://github.com/${GIT_SLUG} "$TEMP/docs-$latest" - curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[0]}/docs/serving-api.md -s > "$TEMP/docs-$latest/docs/reference/api/serving-api.md" + + if (( $(echo "$latest > 1.6" | bc -l) )); then + curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[0]}/docs/serving-api.md -s > "$TEMP/docs-$latest/docs/serving/reference/serving-api.md" + curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[0]}/docs/eventing-api.md -s > "$TEMP/docs-$latest/docs/eventing/reference/eventing-api.md" + else + curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[0]}/docs/serving-api.md -s > "$TEMP/docs-$latest/docs/reference/api/serving-api.md" curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[0]}/docs/eventing-api.md -s > "$TEMP/docs-$latest/docs/reference/api/eventing-api.md" + fi + pushd "$TEMP/docs-$latest"; KNATIVE_VERSION="${VERSIONS[0]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[0]}" mkdocs build -d $SITE/docs; popd # Previous release branches release-$version to /v$version-docs @@ -64,8 +71,13 @@ else echo "Building for previous version $version" git clone --depth 1 -b ${DOCS_BRANCHES[$i+1]} https://github.com/${GIT_SLUG} "$TEMP/docs-$version" - curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[i+1]}/docs/serving-api.md -s > "$TEMP/docs-$version/docs/reference/api/serving-api.md" - curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[i+1]}/docs/eventing-api.md -s > "$TEMP/docs-$version/docs/reference/api/eventing-api.md" + if (( $(echo "$version > 1.6" | bc -l) )); then + curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[i+1]}/docs/serving-api.md -s > "$TEMP/docs-$version/docs/serving/reference/serving-api.md" + curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[i+1]}/docs/eventing-api.md -s > "$TEMP/docs-$version/docs/eventing/reference/eventing-api.md" + else + curl -f -L --show-error https://raw.githubusercontent.com/knative/serving/${DOCS_BRANCHES[i+1]}/docs/serving-api.md -s > "$TEMP/docs-$version/docs/reference/api/serving-api.md" + curl -f -L --show-error https://raw.githubusercontent.com/knative/eventing/${DOCS_BRANCHES[i+1]}/docs/eventing-api.md -s > "$TEMP/docs-$version/docs/reference/api/eventing-api.md" + fi pushd "$TEMP/docs-$version"; KNATIVE_VERSION="${VERSIONS[i+1]}.0" SAMPLES_BRANCH="${DOCS_BRANCHES[i+1]}" VERSION_WARNING=true mkdocs build -d "$SITE/v$version-docs"; popd done diff --git a/mkdocs.yml b/mkdocs.yml index 41a74e44d..5583c6657 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,6 +34,8 @@ markdown_extensions: - pymdownx.details - pymdownx.snippets: base_path: docs/snippets + url_download: true + check_paths: true - pymdownx.keys - pymdownx.caret - pymdownx.mark diff --git a/requirements.txt b/requirements.txt index 83b0e2f05..3dff17ba6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,9 +1,8 @@ -mkdocs-material==8.2.7 -mkdocs-exclude>=1.0 -mkdocs-macros-plugin>=0.5.12 -mkdocs-awesome-pages-plugin>=2.5 -mkdocs-redirects>=1.0.3 -mkdocs-rss-plugin>=0.18.0 +mkdocs-material==8.3.9 +mkdocs-exclude>=1.0.2 +mkdocs-macros-plugin>=0.7.0 +mkdocs-awesome-pages-plugin>=2.7.0 +mkdocs-redirects>=1.0.4 +mkdocs-rss-plugin>=1.1.0 pygithub==1.55 semver==2.13.0 -