docs: start some basic documentation

uselagoon · Oct 4, 2024 · 87074a4 · 87074a4
1 parent 05887c3
commit 87074a4
Show file tree

Hide file tree

Showing 32 changed files with 1,455 additions and 5 deletions.
diff --git a/Makefile b/Makefile
@@ -1,26 +1,42 @@
 VERSION=$(shell echo $(shell git describe --abbrev=0 --tags)+$(shell git rev-parse --short=8 HEAD))
 BUILD=$(shell date +%FT%T%z)
+GOCMD=go
 GO_VER=1.22
 GOOS=linux
 GOARCH=amd64
 PKG=github.com/uselagoon/build-deploy-tool
 LDFLAGS=-w -s -X ${PKG}/cmd.bdtVersion=${VERSION} -X ${PKG}/cmd.bdtBuild=${BUILD} -X "${PKG}/cmd.goVersion=${GO_VER}"
 
 test: fmt vet
-	go clean -testcache && go test -v ./...
+	$(GOCMD) clean -testcache && $(GOCMD) test -v ./...
 
 fmt:
-	go fmt ./...
+	$(GOCMD) fmt ./...
 
 vet:
-	go vet ./...
+	$(GOCMD) vet ./...
 
 run: fmt vet
-	go run ./main.go
+	$(GOCMD) run ./main.go
 
 build: fmt vet
-	CGO_ENABLED=0 go build -ldflags '${LDFLAGS}' -v
+	CGO_ENABLED=0 $(GOCMD) build -ldflags '${LDFLAGS}' -v
 
 docker-build:
 	DOCKER_BUILDKIT=1 docker build --pull --build-arg GO_VER=${GO_VER} --build-arg VERSION=${VERSION} --build-arg BUILD=${BUILD} --rm -f Dockerfile -t build-deploy-image:local .
 	docker run --entrypoint /bin/bash build-deploy-image:local -c 'build-deploy-tool version'
+
+docs: test
+	$(GOCMD) run main.go --docs
+
+MKDOCS_IMAGE ?= ghcr.io/amazeeio/mkdocs-material
+MKDOCS_SERVE_PORT ?= 8000
+
+.PHONY: serve
+serve:
+	@echo "Starting container to serve documentation"
+	@docker run --rm -it \
+		-p 127.0.0.1:$(MKDOCS_SERVE_PORT):$(MKDOCS_SERVE_PORT) \
+		-v ${PWD}:/docs \
+		--entrypoint sh $(MKDOCS_IMAGE) \
+		-c 'mkdocs serve --dev-addr=0.0.0.0:$(MKDOCS_SERVE_PORT) -f mkdocs.yml'
diff --git a/cmd/root.go b/cmd/root.go
@@ -21,15 +21,28 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
+var docsFlag bool
+
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Use:   "lagoon-build",
 	Short: "A tool to help with generating Lagoon resources for Lagoon builds",
 	Long: `A tool to help with generating Lagoon resources for Lagoon builds
 This tool will read a .lagoon.yml file and also all the required environment variables from
 within a Lagoon build to help with generating the resources`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if docsFlag {
+			err := doc.GenMarkdownTree(cmd, "docs/commands")
+			if err != nil {
+				return err
+			}
+			fmt.Println("Documentation updated")
+		}
+		return nil
+	},
 }
 
 var templateCmd = &cobra.Command{
@@ -99,6 +112,9 @@ func init() {
 	rootCmd.AddCommand(taskCmd)
 	rootCmd.AddCommand(identifyCmd)
 	rootCmd.AddCommand(validateCmd)
+	rootCmd.Flags().BoolVarP(&docsFlag, "docs", "", false, "Generate docs")
+
+	rootCmd.Flags().MarkHidden("docs")
 
 	rootCmd.PersistentFlags().StringP("lagoon-yml", "l", ".lagoon.yml",
 		"The .lagoon.yml file to read")

diff --git a/docs/commands/lagoon-build.md b/docs/commands/lagoon-build.md
@@ -0,0 +1,57 @@
+## lagoon-build
+
+A tool to help with generating Lagoon resources for Lagoon builds
+
+### Synopsis
+
+A tool to help with generating Lagoon resources for Lagoon builds
+This tool will read a .lagoon.yml file and also all the required environment variables from
+within a Lagoon build to help with generating the resources
+
+```
+lagoon-build [flags]
+```
+
+### Options
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+  -h, --help                               help for lagoon-build
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build configuration](lagoon-build_configuration.md)	 - Generate configurations
+* [lagoon-build identify](lagoon-build_identify.md)	 - Identify resources
+* [lagoon-build tasks](lagoon-build_tasks.md)	 - Run tasks
+* [lagoon-build template](lagoon-build_template.md)	 - Generate templates
+* [lagoon-build validate](lagoon-build_validate.md)	 - Validate resources
+* [lagoon-build version](lagoon-build_version.md)	 - Version information
+
+###### Auto generated by spf13/cobra on 4-Oct-2024
diff --git a/docs/commands/lagoon-build_configuration.md b/docs/commands/lagoon-build_configuration.md
@@ -0,0 +1,52 @@
+## lagoon-build configuration
+
+Generate configurations
+
+### Synopsis
+
+Generate any configurations for Lagoon builds
+
+### Options
+
+```
+  -h, --help   help for configuration
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build](lagoon-build.md)	 - A tool to help with generating Lagoon resources for Lagoon builds
+* [lagoon-build configuration fastly](lagoon-build_configuration_fastly.md)	 - Generate fastly configuration for a specific ingress domain
+
+###### Auto generated by spf13/cobra on 4-Oct-2024
diff --git a/docs/commands/lagoon-build_configuration_fastly.md b/docs/commands/lagoon-build_configuration_fastly.md
@@ -0,0 +1,52 @@
+## lagoon-build configuration fastly
+
+Generate fastly configuration for a specific ingress domain
+
+```
+lagoon-build configuration fastly [flags]
+```
+
+### Options
+
+```
+  -D, --domain string   The .lagoon.yml file to read
+  -h, --help            help for fastly
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build configuration](lagoon-build_configuration.md)	 - Generate configurations
+
+###### Auto generated by spf13/cobra on 4-Oct-2024
diff --git a/docs/commands/lagoon-build_identify.md b/docs/commands/lagoon-build_identify.md
@@ -0,0 +1,60 @@
+## lagoon-build identify
+
+Identify resources
+
+### Synopsis
+
+Identify resources for Lagoon builds
+
+### Options
+
+```
+  -h, --help   help for identify
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build](lagoon-build.md)	 - A tool to help with generating Lagoon resources for Lagoon builds
+* [lagoon-build identify created-ingress](lagoon-build_identify_created-ingress.md)	 - Identify all created ingress object names for a specific environment
+* [lagoon-build identify dbaas](lagoon-build_identify_dbaas.md)	 - Identify if any dbaas consumers are created
+* [lagoon-build identify feature](lagoon-build_identify_feature.md)	 - Identify if a feature flag has been enabled
+* [lagoon-build identify image-builds](lagoon-build_identify_image-builds.md)	 - Identify the configuration for building images for a Lagoon build
+* [lagoon-build identify ingress](lagoon-build_identify_ingress.md)	 - Identify all ingress for a specific environment
+* [lagoon-build identify ingress](lagoon-build_identify_ingress.md)	 - Identify all ingress for a specific environment
+* [lagoon-build identify lagoon-services](lagoon-build_identify_lagoon-services.md)	 - Identify the lagoon services for a Lagoon build
+* [lagoon-build identify native-cronjobs](lagoon-build_identify_native-cronjobs.md)	 - Identify any native cronjobs for a specific environment
+* [lagoon-build identify primary-ingress](lagoon-build_identify_primary-ingress.md)	 - Identify the primary ingress for a specific environment
+
+###### Auto generated by spf13/cobra on 4-Oct-2024
diff --git a/docs/commands/lagoon-build_identify_created-ingress.md b/docs/commands/lagoon-build_identify_created-ingress.md
@@ -0,0 +1,51 @@
+## lagoon-build identify created-ingress
+
+Identify all created ingress object names for a specific environment
+
+```
+lagoon-build identify created-ingress [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for created-ingress
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --active-environment string          Name of the active environment if known
+  -b, --branch string                      The name of the branch
+  -d, --build-type string                  The type of build (branch, pullrequest, promote)
+      --default-backup-schedule string     The default backup schedule to use
+  -e, --environment-name string            The environment name to check
+  -E, --environment-type string            The type of environment (development or production)
+      --environment-variables string       The JSON payload for environment scope variables
+  -A, --fastly-api-secret-prefix string    The fastly secret prefix to use (default "fastly-api-")
+  -F, --fastly-cache-no-cache-id string    The fastly cache no cache service ID to use
+  -f, --fastly-service-id string           The fastly service ID to use
+      --ignore-missing-env-files           Ignore missing env_file files (true by default, subject to change). (default true)
+      --ignore-non-string-key-errors       Ignore non-string-key docker-compose errors (true by default, subject to change). (default true)
+      --images string                      JSON representation of service:image reference
+  -L, --lagoon-version string              The lagoon version
+  -l, --lagoon-yml string                  The .lagoon.yml file to read (default ".lagoon.yml")
+      --lagoon-yml-override string         The .lagoon.yml override file to read for merging values into target lagoon.yml (default ".lagoon.override.yml")
+  -M, --monitoring-config string           The monitoring contact config if known
+  -m, --monitoring-status-page-id string   The monitoring status page ID if known
+  -p, --project-name string                The project name
+      --project-variables string           The JSON payload for project scope variables
+  -B, --pullrequest-base-branch string     The pullrequest base branch
+  -H, --pullrequest-head-branch string     The pullrequest head branch
+  -P, --pullrequest-number string          The pullrequest number
+      --pullrequest-title string           The pullrequest title
+  -T, --saved-templates-path string        Path to where the resulting templates are saved (default "/kubectl-build-deploy/lagoon/services-routes")
+  -s, --standby-environment string         Name of the standby environment if known
+  -t, --template-path string               Path to the template on disk (default "/kubectl-build-deploy/")
+```
+
+### SEE ALSO
+
+* [lagoon-build identify](lagoon-build_identify.md)	 - Identify resources
+
+###### Auto generated by spf13/cobra on 4-Oct-2024