Document Dependencies (Azure#3496)

* Create file header and footer

* Add documentation to script

* Add new target to Taskfile

* Add generated documentation file

* Address PR feedback

Author: theunrepentantgeek

.devcontainer/install-dependencies.sh

@@ -24,6 +24,18 @@ set -eu
 # -s --skip-installed   : Skip anything that's already installed
 #
 
+#
+# This file includes documentation in lines prefixed `#doc#`.
+# These lines are extracted by running `task doc:dependencies` from the root folder.
+#
+# Each depencency should be documented by a single line with the following content:
+#
+# | <name> | <version> | <details> |
+#
+# Details should include at minimum a link to the originating website. 
+# Be sure to use include the `#doc#` prefix on each line.
+#
+
 VERBOSE=false
 SKIP=false
 DEVCONTAINER=false
@@ -82,6 +94,7 @@ fi
 
 # Ensure we have the right version of GO
 
+#doc# | Go | 1.20 | https://golang.org/doc/install #
 if ! command -v go > /dev/null 2>&1; then
     write-error "Go must be installed manually; see https://golang.org/doc/install"
     exit 1
@@ -91,14 +104,15 @@ GOVER=$(go version)
 write-info "Go version: ${GOVER[*]}"
 
 GOVERREQUIRED="go1.20.*"
-GOVERACTUAL=$(go version | { read _ _ ver _; echo $ver; })
+GOVERACTUAL=$(go version | { read _ _ ver _; echo "$ver"; })
 if ! [[ "$GOVERACTUAL" =~ $GOVERREQUIRED ]]; then
     write-error "Go must be version $GOVERREQUIRED, not $GOVERACTUAL; see : https://golang.org/doc/install"
     exit 1
 fi
 
 # Ensure we have AZ
 
+#doc# | AZ | latest | https://docs.microsoft.com/en-us/cli/azure/install-azure-cli |
 if ! command -v az > /dev/null 2>&1; then
     write-error "Azure CLI must be installed manually: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli"
     exit 1
@@ -145,25 +159,39 @@ go-install() {
     fi
 }
 
+#doc# | conversion-gen | v0.28.0 | https://pkg.go.dev/k8s.io/code-generator/cmd/conversion-gen |
 go-install conversion-gen k8s.io/code-generator/cmd/[email protected]
+
+#doc# | controller-gen | v0.13.0 | https://book.kubebuilder.io/reference/controller-gen |
 go-install controller-gen sigs.k8s.io/controller-tools/cmd/[email protected]
+
+#doc# | kind | v0.20.0 | https://kind.sigs.k8s.io/ |
 go-install kind sigs.k8s.io/[email protected]
+
+#doc# | kustomize | v4.5.7 | https://kustomize.io/ |
 go-install kustomize sigs.k8s.io/kustomize/kustomize/[email protected]
 
 # for docs site
+
+#doc# | hugo | v0.88.1 | https://gohugo.io/ |
 go-install hugo -tags extended github.com/gohugoio/[email protected]
+
+#doc# | htmltest | latest | https://github.com/wjdp/htmltest (but see https://github.com/theunrepentantgeek/htmltest for our custom build )
 # Restore this to github.com/wjdp/htmltest@v?? once PR#215 is merged with the feature we need
 go-install htmltest github.com/theunrepentantgeek/htmltest@latest
 
 # for api docs 
 # TODO: Replace this with the new release tag.
 # Currently pinned just after a couple of fixes from @theunrepentantgeek
+#doc# | gen-crd-api-reference-docs | 11fe95cb | https://github.com/ahmetb/gen-crd-api-reference-docs |
 go-install gen-crd-api-reference-docs github.com/ahmetb/gen-crd-api-reference-docs@11fe95cbdcb91e9c25446fc99e6f2cdd8cbeb91a
 
 # Install envtest tooling - ideally version here should match that used in v2/go.mod, but only @latest works
+#doc# | setup-envtest | latest | https://book.kubebuilder.io/reference/envtest.html |
 go-install setup-envtest sigs.k8s.io/controller-runtime/tools/setup-envtest@latest
 
 # Install golangci-lint
+#doc# | golangci-lint | 1.51.2 | https://github.com/golangci/golangci-lint |
 write-verbose "Checking for $TOOL_DEST/golangci-lint"
 if should-install "$TOOL_DEST/golangci-lint"; then
     write-info "Installing golangci-lint"
@@ -173,27 +201,31 @@ if should-install "$TOOL_DEST/golangci-lint"; then
 fi
 
 # Install Task
+#doc# | Task | v3.31 | https://taskfile.dev/ |
 write-verbose "Checking for $TOOL_DEST/go-task"
 if should-install "$TOOL_DEST/task"; then 
     write-info "Installing go-task"
     curl -sL "https://github.com/go-task/task/releases/download/v3.31.0/task_linux_amd64.tar.gz" | tar xz -C "$TOOL_DEST" task
 fi
 
 # Install Trivy
+#doc# | Trivy | v0.37.3 | https://trivy.dev/ |
 write-verbose "Checking for $TOOL_DEST/trivy"
 if should-install "$TOOL_DEST/trivy"; then
     write-info "Installing trivy"
     curl -sL "https://github.com/aquasecurity/trivy/releases/download/v0.37.3/trivy_0.37.3_Linux-64bit.tar.gz" | tar xz -C "$TOOL_DEST" trivy
 fi
 
 # Install helm
+#doc# | Helm | v3.8.0 | https://helm.sh/ |
 write-verbose "Checking for $TOOL_DEST/helm"
 if should-install "$TOOL_DEST/helm"; then
     write-info "Installing helm…"
     curl -sL "https://get.helm.sh/helm-v3.8.0-linux-amd64.tar.gz" | tar -C "$TOOL_DEST" --strip-components=1 -xz linux-amd64/helm
 fi
 
 # Install yq
+#doc# | YQ | v4.13.0 | https://github.com/mikefarah/yq/ |
 yq_version=v4.13.0
 yq_binary=yq_linux_amd64
 write-verbose "Checking for $TOOL_DEST/yq"
@@ -204,6 +236,7 @@ if should-install "$TOOL_DEST/yq"; then
 fi
 
 # Install cmctl, used to wait for cert manager installation during some tests cases
+#doc# | cmctl | latest | https://cert-manager.io/docs/reference/cmctl |
 os=$(go env GOOS)
 arch=$(go env GOARCH)
 write-verbose "Checking for $TOOL_DEST/cmctl"
@@ -213,6 +246,7 @@ if should-install "$TOOL_DEST/cmctl"; then
 fi
 
 write-verbose "Checking for $BUILDX_DEST/docker-buildx"
+#doc# | BuildX | v0.11.2 | https://github.com/docker/buildx |
 if should-install "$BUILDX_DEST/docker-buildx"; then
     write-info "Installing buildx-${os}_${arch} to $BUILDX_DEST…"
     mkdir -p "$BUILDX_DEST"
@@ -221,13 +255,15 @@ if should-install "$BUILDX_DEST/docker-buildx"; then
 fi
 
 # Install azwi
+#doc# | AZWI | v1.0.0 | https://github.com/Azure/azure-workload-identity |
 write-verbose "Checking for $TOOL_DEST/azwi"
 if should-install "$TOOL_DEST/azwi"; then
     write-info "Installing azwi…"
     curl -sL "https://github.com/Azure/azure-workload-identity/releases/download/v1.0.0/azwi-v1.0.0-${os}-${arch}.tar.gz" | tar xz -C "$TOOL_DEST" azwi
 fi
 
 # Ensure tooling for Hugo is available
+#doc# | PostCSS | latest | https://postcss.org/ |
 write-verbose "Checking for /usr/bin/postcss"
 if ! which postcss  > /dev/null 2>&1; then 
     write-info "Installing postcss"

Taskfile.yml

@@ -1024,6 +1024,13 @@ tasks:
     cmds:
       - "{{.SCRIPTS_ROOT}}/check_frontmatter.py"
 
+  doc:dependencies:
+    desc: Generate documentation for depencencies
+    cmds:
+      - cp ./docs/v2/dependencies-header.md ./docs/hugo/content/contributing/dependencies.md
+      - grep '^[[:space:]]*#doc#' .devcontainer/install-dependencies.sh | sed -e 's/[[:space:]]*#doc# //' | sort -f >> ./docs/hugo/content/contributing/dependencies.md
+      - cat ./docs/v2/dependencies-footer.md >> ./docs/hugo/content/contributing/dependencies.md
+
   ############### Shared targets ###############
 
   cleanup-azure-resources:

docs/hugo/content/contributing/dependencies.md

@@ -0,0 +1,43 @@
+---
+title: Developer Dependencies
+linktitle: Dependencies
+---
+Development of Azure Service Operator depends on a number of development tools and libraries that need to be installed. 
+
+If you prefer to install those dependencies manually (instead of using the `.devcontainer/install-dependencies.sh` script), here is a list of what's required. 
+
+| Dependency | Version | Reference |
+|:---------- |:-------:|:--------- |
+| AZWI | v1.0.0 | https://github.com/Azure/azure-workload-identity |
+| BuildX | v0.11.2 | https://github.com/docker/buildx |
+| cmctl | latest | https://cert-manager.io/docs/reference/cmctl |
+| controller-gen | v0.13.0 | https://book.kubebuilder.io/reference/controller-gen |
+| conversion-gen | v0.28.0 | https://pkg.go.dev/k8s.io/code-generator/cmd/conversion-gen |
+| gen-crd-api-reference-docs | 11fe95cb | https://github.com/ahmetb/gen-crd-api-reference-docs |
+| golangci-lint | 1.51.2 | https://github.com/golangci/golangci-lint |
+| Helm | v3.8.0 | https://helm.sh/ |
+| htmltest | latest | https://github.com/wjdp/htmltest (but see https://github.com/theunrepentantgeek/htmltest for our custom build )
+| hugo | v0.88.1 | https://gohugo.io/ |
+| kind | v0.20.0 | https://kind.sigs.k8s.io/ |
+| kustomize | v4.5.7 | https://kustomize.io/ |
+| PostCSS | latest | https://postcss.org/ |
+| setup-envtest | latest | https://book.kubebuilder.io/reference/envtest.html |
+| Task | v3.31 | https://taskfile.dev/ |
+| Trivy | v0.37.3 | https://trivy.dev/ |
+| YQ | v4.13.0 | https://github.com/mikefarah/yq/ |
+
+Dependencies are listed alphabetically. Refer to `install-dependencies.sh` for a recommended order of installation.
+
+To update this file:
+
+* Modify the file header content in `docs/v2/dependencies-header.md`;
+* Modify the file footer in `docs/v2/dependencies-footer.md`; or
+* Modify the dependencies installed by `.devcontainer/install-dependencies.sh`.
+
+Regenerate the file using task:
+
+``` bash
+$ task doc:dependencies
+```
+
+Finally, submit the update as a PR.

docs/v2/dependencies-footer.md

@@ -0,0 +1,16 @@
+
+Dependencies are listed alphabetically. Refer to `install-dependencies.sh` for a recommended order of installation.
+
+To update this file:
+
+* Modify the file header content in `docs/v2/dependencies-header.md`;
+* Modify the file footer in `docs/v2/dependencies-footer.md`; or
+* Modify the dependencies installed by `.devcontainer/install-dependencies.sh`.
+
+Regenerate the file using task:
+
+``` bash
+$ task doc:dependencies
+```
+
+Finally, submit the update as a PR.

docs/v2/dependencies-header.md

@@ -0,0 +1,10 @@
+---
+title: Developer Dependencies
+linktitle: Dependencies
+---
+Development of Azure Service Operator depends on a number of development tools and libraries that need to be installed. 
+
+If you prefer to install those dependencies manually (instead of using the `.devcontainer/install-dependencies.sh` script), here is a list of what's required. 
+
+| Dependency | Version | Reference |
+|:---------- |:-------:|:--------- |