From 01c8fc854a74c4cb50f997e57ab71fd0e6be6e93 Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Fri, 17 Nov 2023 23:10:38 +0100 Subject: [PATCH 1/2] Correct small mistakes throughout the docs --- docs/bundle-runtime.md | 10 +++++----- docs/bundle-secrets.md | 2 +- docs/bundle.md | 4 ++-- docs/gitops-flux.md | 2 +- docs/module-sign.md | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/bundle-runtime.md b/docs/bundle-runtime.md index c131b3f2..5db740bf 100644 --- a/docs/bundle-runtime.md +++ b/docs/bundle-runtime.md @@ -150,11 +150,6 @@ Currently, the only supported value is `v1alpha1`. The `name` is a required field used to identify the Runtime. -### Optional - -The `optional` field can be set to `true` and Timoni will skip -not found Kubernetes resources instead of throwing an error. - ### Values The `values` array is a required field that specifies the list of Kubernetes resources and the fields to be extracted. @@ -227,6 +222,11 @@ runtime: { The CUE expression must result in a concrete value of type `string`, `number` or `bool`. +#### Optional + +The `optional` field can be set to `true` and Timoni will skip +not found Kubernetes resources instead of throwing an error. + ## Using values from Kubernetes API The values defined in a Runtime can be referred in Bundles using CUE attributes. diff --git a/docs/bundle-secrets.md b/docs/bundle-secrets.md index 8708df82..11361e3f 100644 --- a/docs/bundle-secrets.md +++ b/docs/bundle-secrets.md @@ -124,7 +124,7 @@ When using [SOPS](https://github.com/getsops/sops), we can decrypt the secrets and [inject](https://github.com/getsops/sops#passing-secrets-to-other-processes) those values to env vars, then use `--runtime-from-env`. -Another option is to extract the secret values of a Timoni Bundle to an YAML or JSON file, +Another option is to extract the secret values of a Timoni Bundle to a YAML or JSON file, that we encrypt/decrypt with SOPS. ### Injecting secrets from SOPS diff --git a/docs/bundle.md b/docs/bundle.md index d281ca07..f8d9fc40 100644 --- a/docs/bundle.md +++ b/docs/bundle.md @@ -290,7 +290,7 @@ and will pull the module by its OCI digest. ### Instance Namespace -The `instance.module` is a required field that specifies the Kubernetes namespace where the instance is created. +The `instance.namespace` is a required field that specifies the Kubernetes namespace where the instance is created. If the specified namespace does not exist, Timoni will first create the namespace, then it will apply the instance's resources in that namespace. @@ -315,7 +315,7 @@ values: { } ``` -To make an Runtime attribute required, the field value can be set to its type: +To make a Runtime attribute required, the field value can be set to its type: ```cue values: { diff --git a/docs/gitops-flux.md b/docs/gitops-flux.md index a9696539..ac159881 100644 --- a/docs/gitops-flux.md +++ b/docs/gitops-flux.md @@ -35,7 +35,7 @@ in Kubernetes, will pick up the latest changes and deploy them on the cluster. ## Continuous Delivery workflow -In the Git repository where Flux was bootstrap, we'll configure the reconciliation +In the Git repository where Flux was bootstrapped, we'll configure the reconciliation of the Kubernetes resources pushed to the container registry. ```yaml diff --git a/docs/module-sign.md b/docs/module-sign.md index ba88c4bb..6f816879 100644 --- a/docs/module-sign.md +++ b/docs/module-sign.md @@ -6,7 +6,7 @@ the OCI artifact can be cryptographically signed to improve the software supply ## Cosign Timoni can sign modules using Sigstore Cosign. -[Cosign](https://github.com/sigstore/cosign) is tool that allows you to sign and verify +[Cosign](https://github.com/sigstore/cosign) is a tool that allows you to sign and verify OCI artifacts with a public/private key pair or with an OIDC token provided by GitHub, Google or Microsoft. To sign modules, you need to [install](https://docs.sigstore.dev/system_config/installation/) From 90cf1d98d4dbbffa1b05e705f8142d4df65cb2e1 Mon Sep 17 00:00:00 2001 From: Daniel Bodky Date: Fri, 17 Nov 2023 23:11:34 +0100 Subject: [PATCH 2/2] Add mkdoc setup to CONTRIBUTING.md --- .gitignore | 3 ++- CONTRIBUTING.md | 17 +++++++++++++++++ hack/mkdocs/requirements.txt | 1 + 3 files changed, 20 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index b7c4ded7..e309a195 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *.out .DS_Store bin/ -docs/cmd/ \ No newline at end of file +docs/cmd/ +venv/ \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ecddce4d..89da63f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,23 @@ Run manual tests using the locally built binary: ./bin/timoni ``` +## How to render the docs locally + +Prerequisites can be found and installed from [`./hack/mkdocs/requirements.txt`](/hack/mkdocs/requirements.txt): + +```shell +python -m venv venv && source venv/bin/activate +pip install -r hack/mkdocs/requirements.txt +``` + +The docs can then be built and served locally with: + +```shell +mkdocs serve +``` + +By default, MKDocs will be served at [http://127.0.0.1:8000](http://127.0.0.1:8000) + ## Acceptance policy These things will make a PR more likely to be accepted: diff --git a/hack/mkdocs/requirements.txt b/hack/mkdocs/requirements.txt index 6b63648c..0508010e 100644 --- a/hack/mkdocs/requirements.txt +++ b/hack/mkdocs/requirements.txt @@ -10,6 +10,7 @@ pymdown-extensions~=10.2 # Requirements for mkdocs plugins babel~=2.10 colorama~=0.4 +mkdocs-redirects~=1.2 paginate~=0.5 regex>=2022.4 requests~=2.26