General cleanup of sample and ref docs (#5117)

* General cleanup of sample and ref docs

* move reference docs

* fix nav and links

* update redirects

* fix comment

* added Paul's script updates, updating ext versions

code-samples/community/README.md

@@ -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. |

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

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

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

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.

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.

docs/reference/README.md

@@ -1,3 +0,0 @@
-# Knative Reference Documentation
-
-Knative reference documentation.

docs/reference/client/README.md

@@ -1,3 +0,0 @@
-# Knative Client Reference
-
-See the [`kn` documentation]({{ clientdocs() }}){target=_blank} in Github.

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/)
+<!--LINK TITLES must match the title of the sample page they link to to avoid confusion and provide a consistent UX). If descriptions are required here, this should be converted to a table as above-->
 
-_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.

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.

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

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

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
-