Merge pull request #3435 from xrstf/improve-docs

fix docs validation in Pull Requests

Author: kcp-ci-bot

.github/workflows/docs-gen-and-push.yaml

@@ -1,4 +1,4 @@
-name: Generate and push docs
+name: Documentation
 
 on:
   # So we can trigger manually if needed
@@ -24,7 +24,7 @@ concurrency:
 
 jobs:
   generate-and-push:
-    name: Generate and push docs
+    name: Generate and push
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
@@ -42,4 +42,10 @@ jobs:
           python-version: '3.10'
           cache: 'pip'
 
+      # mike does not support giving CLI flags for mkdocs, but we also do not
+      # want to permanently enable strict mode, so here we enable it just for this
+      # task
+      - run: |
+          echo "strict: true" >> docs/mkdocs.yml
+
       - run: make generate-cli-docs generate-api-docs deploy-docs

Makefile

@@ -163,12 +163,11 @@ update-contextual-logging: $(LOGCHECK) ## Update contextual logging
 .PHONY: generate-cli-docs
 generate-cli-docs: ## Generate cli docs
 	git clean -fdX docs/content/reference/cli
-	pushd . && cd docs/generators/cli-doc && go build . && popd
-	./docs/generators/cli-doc/cli-doc -output docs/content/reference/cli
+	cd ./docs/generators/cli-doc && go run . -output ../../content/reference/cli
 
 .PHONY: generate-api-docs
 generate-api-docs: ## Generate api docs
-	git clean -fdX docs/content/reference/api
+	git clean -fdX docs/content/reference/crd
 	docs/generators/crd-ref/run-crd-ref-gen.sh
 
 VENVDIR=$(abspath docs/venv)

cli/pkg/bind/cmd/cmd.go

@@ -28,15 +28,15 @@ import (
 
 var (
 	bindExampleUses = `
-	# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace.
-	%[1]s bind apiexport root:my-service:my-export --name my-binding
+# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace.
+%[1]s bind apiexport root:my-service:my-export --name my-binding
 
-	# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace with accepted permission claims.
-	%[1]s bind apiexport root:my-service:my-export --name my-binding --accept-permission-claim secrets.core,configmaps.core
+# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace with accepted permission claims.
+%[1]s bind apiexport root:my-service:my-export --name my-binding --accept-permission-claim secrets.core,configmaps.core
 
-	# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace with rejected permission claims.
-	%[1]s bind apiexport root:my-service:my-export --name my-binding --reject-permission-claim secrets.core,configmaps.core
-	`
+# Create an APIBinding named "my-binding" that binds to the APIExport "my-export" in the "root:my-service" workspace with rejected permission claims.
+%[1]s bind apiexport root:my-service:my-export --name my-binding --reject-permission-claim secrets.core,configmaps.core
+`
 )
 
 func New(streams genericclioptions.IOStreams) *cobra.Command {

cli/pkg/claims/cmd/cmd.go

@@ -30,12 +30,12 @@ import (
 // TODO: Add examples for edit and update claims.
 var (
 	claimsExample = `
-	# Lists the permission claims and their respective status related to a specific APIBinding.
-	%[1]s claims get apibinding cert-manager
+# Lists the permission claims and their respective status related to a specific APIBinding.
+%[1]s claims get apibinding cert-manager
 
-	# List permission claims and their respective status for all APIBindings in current workspace.
-	%[1]s claims get apibinding
-	`
+# List permission claims and their respective status for all APIBindings in current workspace.
+%[1]s claims get apibinding
+`
 )
 
 // New returns a cobra.Command for claims related actions.

cli/pkg/crd/cmd/cmd.go

@@ -28,12 +28,12 @@ import (
 
 var (
 	crdExample = `
-	# Convert a CRD in a yaml file to an APIResourceSchema. For a CRD named widgets.example.io, and a prefix value of
-	# 'today', the new APIResourceSchema's name will be today.widgets.example.io.
-	%[1]s crd snapshot -f crd.yaml --prefix 2022-05-07 > api-resource-schema.yaml
+# Convert a CRD in a yaml file to an APIResourceSchema. For a CRD named widgets.example.io, and a prefix value of
+# 'today', the new APIResourceSchema's name will be today.widgets.example.io.
+%[1]s crd snapshot -f crd.yaml --prefix 2022-05-07 > api-resource-schema.yaml
 
-	# Convert a CRD from STDIN
-	kubectl get crd foo -o yaml | %[1]s crd snapshot -f - --prefix today > output.yaml
+# Convert a CRD from STDIN
+kubectl get crd foo -o yaml | %[1]s crd snapshot -f - --prefix today > output.yaml
 `
 )
 

cli/pkg/workspace/cmd/cmd.go

@@ -30,44 +30,44 @@ import (
 
 var (
 	workspaceExample = `
-	# shows the workspace you are currently using
-	%[1]s workspace .
+# shows the workspace you are currently using
+%[1]s workspace .
 
-	# enter a given workspace (this will change the current-context of your current KUBECONFIG)
-	%[1]s workspace use my-workspace
+# enter a given workspace (this will change the current-context of your current KUBECONFIG)
+%[1]s workspace use my-workspace
 
-	# short-hand for the use syntax
-	%[1]s workspace my-workspace
+# short-hand for the use syntax
+%[1]s workspace my-workspace
 
-	# enter a given absolute workspace
-	%[1]s workspace :root:default:my-workspace
+# enter a given absolute workspace
+%[1]s workspace :root:default:my-workspace
 
-	# short-hand for the current root workspace
-	%[1]s workspace :
+# short-hand for the current root workspace
+%[1]s workspace :
 
-	# enter a given relative workspace
-	%[1]s workspace some:nested:workspace
+# enter a given relative workspace
+%[1]s workspace some:nested:workspace
 
-	# enter the parent workspace
-	%[1]s workspace ..
+# enter the parent workspace
+%[1]s workspace ..
 
-	# enter the grand parent workspace
-	%[1]s workspace ..:..
+# enter the grand parent workspace
+%[1]s workspace ..:..
 
-	# enter the previous workspace
-	%[1]s workspace -
+# enter the previous workspace
+%[1]s workspace -
 
-	# go to your home workspace
-	%[1]s workspace
+# go to your home workspace
+%[1]s workspace
 
-	# create a workspace and immediately enter it
-	%[1]s workspace create my-workspace --enter
+# create a workspace and immediately enter it
+%[1]s workspace create my-workspace --enter
 
-	# create a context with the current workspace, e.g. root:default:my-workspace
-	%[1]s workspace create-context
+# create a context with the current workspace, e.g. root:default:my-workspace
+%[1]s workspace create-context
 
-	# create a context with the current workspace, named context-name
-	%[1]s workspace create-context context-name
+# create a context with the current workspace, named context-name
+%[1]s workspace create-context context-name
 `
 )
 

docs/content/concepts/apis/exporting-apis.md

@@ -159,16 +159,16 @@ exported APIs need to know and reference it.
 
 Given 2 Workspaces, each with its own `APIExport` that exports `widgets.example.kcp.io`, kcp uses the identity hash (in
 a mostly transparent manner) to ensure the correct instances associated with the appropriate `APIResourceSchema` are
-served to clients. See [Run Your Controller](#Run-Your-Controller) for more information.
+served to clients. See [Build Your Controller](#build-your-controller) for more information.
 
 ### Permission Claims
 
 When a consumer creates an `APIBinding` that binds to an `APIExport`, the API provider who owns the `APIExport`
 implicitly has access to instances of the exported APIs in the consuming workspace. There are also times when the API
 provider needs to access additional resource data in a consuming workspace. These resources might come from other
-APIExports the consumer has created `APIBindings` for, or from APIs that are built in to kcp. The API provider 
-requests access to these additional resources by adding `PermissionClaims` for the desired API's group, resource, and 
-identity hash to their `APIExport`. Let's take the example `APIExport` from above and add permission claims for 
+APIExports the consumer has created `APIBindings` for, or from APIs that are built in to kcp. The API provider
+requests access to these additional resources by adding `PermissionClaims` for the desired API's group, resource, and
+identity hash to their `APIExport`. Let's take the example `APIExport` from above and add permission claims for
 `ConfigMaps` and `Things`:
 
 ```yaml
@@ -196,9 +196,9 @@ spec:
 3. To claim another exported API, you must include its `identityHash`
 4. If you aren't claiming access to individual instances, you must specify `all` instead
 
-This is essentially a request from the APIProvider, asking each consumer to grant permission for the claimed 
+This is essentially a request from the APIProvider, asking each consumer to grant permission for the claimed
 resources. If the consumer does not accept a permission claim, the API Provider is not allowed to access the claimed
-resources. Consumer acceptance of permission claims is part of the `APIBinding` spec. For more details, see the 
+resources. Consumer acceptance of permission claims is part of the `APIBinding` spec. For more details, see the
 section on [APIBindings](#apibinding).
 
 ### Maximal Permission Policy
@@ -207,7 +207,7 @@ If you want to set an upper bound on what is allowed for a consumer of your expo
 permission policy" using standard RBAC resources. This is optional; if the policy is not set, no upper bound is applied,
 and a consuming user is authorized based on the RBAC configuration in the consuming workspace.
 
-The maximal permission policy consists of RBAC `(Cluster)Roles` and `(Cluster)RoleBindings`. Incoming requests to a 
+The maximal permission policy consists of RBAC `(Cluster)Roles` and `(Cluster)RoleBindings`. Incoming requests to a
 workspace that binds to an APIExport are additionally checked against
 these rules, with the username and groups prefixed with `apis.kcp.io:binding:`.
 
@@ -227,7 +227,7 @@ spec:
     local: {} # (1)
 ```
 
-1. `local` is the only supported option at the moment. "Local" means the RBAC policy is defined in the same 
+1. `local` is the only supported option at the moment. "Local" means the RBAC policy is defined in the same
    workspace as the `APIExport`.
 
 We don't want users to be able to mutate the `status` subresource, so we set up
@@ -269,14 +269,14 @@ subjects:
   name: apis.kcp.io:binding:system:authenticated # (1)
 ```
 
-1. Note the `apis.kcp.io:binding:` prefix; this identifies this `ClusterRoleBinding` as part of the maximal 
+1. Note the `apis.kcp.io:binding:` prefix; this identifies this `ClusterRoleBinding` as part of the maximal
    permission policy. It applies to `system:authenticated`.
 
-Now imagine a user named `unicorn` with group `system:authenticated`. They create a workspace named 
-`magic` and bind to the `tenancy.kcp.io` APIExport from the workspace `root`. What actions `unicorn` is allowed to 
+Now imagine a user named `unicorn` with group `system:authenticated`. They create a workspace named
+`magic` and bind to the `tenancy.kcp.io` APIExport from the workspace `root`. What actions `unicorn` is allowed to
 perform in the `magic` workspace must be granted by **both**:
 
-1. the standard RBAC authorization flow in the `magic` workspace; i.e., `(Cluster)Roles` and `(Cluster)RoleBindings` 
+1. the standard RBAC authorization flow in the `magic` workspace; i.e., `(Cluster)Roles` and `(Cluster)RoleBindings`
    in the `magic` workspace itself, **and**
 2. the maximal permission policy RBAC settings configured in the `root` workspace for the `tenancy` APIExport
 

docs/content/concepts/terminology.md

@@ -23,7 +23,7 @@ where different logical clusters can be used by different users in the organizat
 The kcp server only provides resources to accomplish this, such as `LogicalCluster`, `Workspace`, `APIBinding` and
 `APIExport`, on top of some core Kubernetes resources, like `ConfigMap` and `Secret`. It doesn't provide Kubernetes
 resources for managing and orchestrating workloads, such as Pods and Deployments. The list of resources provided by
-default can be found in the [Built-in APIs document](../apis/built-in).
+default can be found in the [Built-in APIs document](apis/built-in.md).
 
 kcp follows the Kubernetes API semantics in each logical cluster, i.e. kcp should be conformant to the subset of the
 Kubernetes conformance suite that applies to the APIs available in kcp. In other words, if you're building a platform
@@ -107,7 +107,7 @@ A Workspace's path is based on the hierarchy and the user provided name. For exa
 
 The workspace path is used for building the workspace URL and for accessing the workspace via the `ws` kubectl plugin.
 
-More information, including examples, can be found in the the [Workspaces document](../workspaces).
+More information, including examples, can be found in the the [Workspaces document](workspaces/index.md).
 
 ### Workspace Types
 
@@ -118,10 +118,10 @@ Workspaces have types, which are mostly oriented around a set of default or opti
 - a workspace intended for building Knative functions might expose only the Knative serving APIs, ConfigMaps, Secrets,
   and optionally enable Knative Eventing APIs.
 
-By default, each workspace has the [built-in APIs installed and available to its users](./apis/built-in).
+By default, each workspace has the [built-in APIs installed and available to its users](apis/built-in.md).
 
 More information, including a list of Workspace Types and examples, can be found in the
-[Workspace Types document](../workspaces/workspace-types/).
+[Workspace Types document](workspaces/workspace-types.md).
 
 ## Virtual Workspaces
 
@@ -131,7 +131,7 @@ HTTP path structure, with each (virtual) logical cluster having its own HTTP end
 As with kcp itself, each of these endpoints looks like a Kubernetes cluster on its own, i.e. with `/api/v1` and API
 groups under `/apis/<group>/<version>`.
 
-The Virtual Logical Clusters are called virtual because they don’t actually have their own storage, i.e. they are not 
+The Virtual Logical Clusters are called virtual because they don’t actually have their own storage, i.e. they are not
 a source of truth, instead they are just proxied representations of the real logical clusters from kcp. In the process
 of proxying, the Virtual Workspace API server might filter the visible objects, hide certain API groups completely, or
 even transform objects depending on the use case (e.g. strip the sensitive data). Also, the permission semantics might
@@ -157,7 +157,7 @@ the objects for the resources they provide and potentially other related objects
 It's important to note that the Virtual Workspaces are not necessarily read-only, but that they can also mutate
 resources in the corresponding real logical cluster.
 
-**Finally, for brevity, the Virtual Workspace API server is often simply called the Virtual Workspace.** 
+**Finally, for brevity, the Virtual Workspace API server is often simply called the Virtual Workspace.**
 The Virtual Workspace doesn't exist as a resource in kcp, it's purely a very flexible API (server) that can connect to
 the kcp server for the sake of gathering and mutating the needed objects.
 
@@ -170,7 +170,7 @@ binary alongside the kcp server.
     In a sharded setup, you need to run the Virtual Workspace (API server) for each kcp shard/server that you have.
 
 More information, including concrete examples and a list of frequently asked questions, can be found in the
-[Virtual Workspaces document](../workspaces/virtual-workspaces/).
+[Virtual Workspaces document](workspaces/virtual-workspaces.md).
 
 ## Exporting/Binding APIs
 
@@ -207,7 +207,7 @@ In the sense of kcp, sharding involves:
 
 A shard hosts its own set of Workspaces. The sharding mechanism in kcp allows you to make the workspace hierarchy span
 many shards transparently, while ensuring you can bind APIs from logical clusters running in different shards.
-The [Sharding documentation](./sharding/shards/) has more details about possibilities of sharding, and we strongly
+The [Sharding documentation](sharding/shards.md) has more details about possibilities of sharding, and we strongly
 recommend reading this document if you want to shard your kcp setup.
 
 In a sharded setup, you'll be sending requests to a component called Front Proxy (`kcp-front-proxy`) instead to a

docs/main.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import copy
+import os.path
 
 def define_env(env):
     """
@@ -55,10 +56,10 @@ def section_items(page, nav, config):
 
             # Copy so we don't modify the original
             child = copy.deepcopy(child)
-            
-            # Subsection nesting that works across any level of nesting
-            # Replaced mkdocs fix_url function
-            child.file.url = child.url.replace(page.url, "./")
+
+            # mkdocs hates if a link in the generated Markdown (!) is already a fully-fledged URL
+            # and not a link to a file anymore, so we replace the URL with the file path here.
+            child.file.url = os.path.basename(child.file.src_uri)
             siblings.append(child)
 
         return siblings

docs/requirements.txt

@@ -1,7 +1,7 @@
 mike==2.1.3
 mkdocs==1.5.3
 mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-macros-plugin==1.0.5
+mkdocs-macros-plugin==1.3.7
 mkdocs-material==9.5.17
 mkdocs-material-extensions==1.3.1
 mkdocs-static-i18n==1.2.2