docs: native project documentation

Makefile

@@ -6,7 +6,7 @@ COUNT?=1
 TEST?=$(shell go list ./...)
 HASHICORP_PACKER_PLUGIN_SDK_VERSION?=$(shell go list -m github.com/hashicorp/packer-plugin-sdk | cut -d " " -f2)
 
-.PHONY: dev
+.PHONY: dev build test install-packer-sdc plugin-check testacc generate docs-deps docs-prepare docs-test docs-test-links docs-test-internal-links docs-test-admonitions docs-test-example-labels docs-test-group-example-tabs docs-test-normalize docs-test-github-alerts docs-build docs-serve docs-serve-version docs-serve-mike docs-serve-mike-only docs-backfill
 
 build:
 	@go build -o ${BINARY}
@@ -18,7 +18,7 @@ dev:
 test:
 	@go test -race -count $(COUNT) $(TEST) -timeout=3m
 
-install-packer-sdc: # Install packer software development command.
+install-packer-sdc: ## Install packer sofware development command
 	@go install github.com/hashicorp/packer-plugin-sdk/cmd/packer-sdc@${HASHICORP_PACKER_PLUGIN_SDK_VERSION}
 
 plugin-check: install-packer-sdc build
@@ -29,7 +29,74 @@ testacc: dev
 
 generate: install-packer-sdc
 	@go generate ./...
+	@go fmt ./...
 	@rm -rf .docs
 	@packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
 	@./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
 	@rm -r ".docs"
+
+DOCS_VENV?=$(CURDIR)/docs-site/.venv
+DOCS_PYTHON=$(DOCS_VENV)/bin/python
+DOCS_PIP=$(DOCS_VENV)/bin/pip
+
+docs-deps:
+	@test -d "$(DOCS_VENV)" || python3 -m venv "$(DOCS_VENV)"
+	@"$(DOCS_PIP)" install -r docs-site/requirements.txt
+
+docs-prepare:
+	@./docs-site/scripts/prepare-docs.sh
+
+docs-test:
+	@./docs-site/scripts/test/test-all.sh
+
+docs-test-links:
+	@./docs-site/scripts/test/test-rewrite-integration-links.sh
+
+docs-test-internal-links:
+	@./docs-site/scripts/test/test-fix-internal-links.sh
+
+docs-test-admonitions:
+	@./docs-site/scripts/test/test-convert-admonitions.sh
+
+docs-test-example-labels:
+	@./docs-site/scripts/test/test-format-example-labels.sh
+
+docs-test-group-example-tabs:
+	@./docs-site/scripts/test/test-group-example-tabs.sh
+
+docs-test-normalize:
+	@./docs-site/scripts/test/test-normalize-list-spacing.sh
+
+docs-test-strip-codegen:
+	@./docs-site/scripts/test/test-strip-codegen-comments.sh
+
+docs-test-repair-fences:
+	@./docs-site/scripts/test/test-repair-code-fences.sh
+
+docs-test-stage-markdown:
+	@./docs-site/scripts/test/test-stage-markdown.sh
+
+docs-test-github-alerts:
+	@./docs-site/scripts/test/test-convert-github-alerts.sh
+
+docs-build: generate docs-deps docs-prepare
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" build --config-file zensical.build.toml
+
+docs-serve: generate docs-deps docs-prepare
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
+
+docs-serve-version: docs-deps
+	@test -n "$(VERSION)" || (echo "VERSION is required, e.g. make docs-serve-version VERSION=2.1.0" && exit 1)
+	@rm -rf .web-docs
+	@git checkout "v$(VERSION)" -- .web-docs
+	@INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
+	@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
+
+docs-serve-mike: generate docs-deps
+	@[ -z "$(VERSIONS)" ] || export MIKE_PREVIEW_VERSIONS="$(VERSIONS)"; ./docs-site/scripts/mike-preview.sh
+
+docs-serve-mike-only: docs-deps
+	@./docs-site/scripts/mike-preview.sh --serve-only
+
+docs-backfill: docs-deps
+	@./docs-site/scripts/mike-backfill.sh $(VERSIONS)

README.md

@@ -131,9 +131,9 @@ Licensed under the [Mozilla Public License, version 2.0][license].
 [desktop-hypervisors]: https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion
 [docs-packer-init]: https://developer.hashicorp.com/packer/docs/commands/init
 [docs-packer-plugin-install]: https://developer.hashicorp.com/packer/docs/plugins/install-plugins
-[docs-vmware-plugin]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/
-[docs-vmware-iso]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/components/builder/iso
-[docs-vmware-vmx]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/components/builder/vmx
+[docs-vmware-plugin]: https://vmware.github.io/packer-plugin-vmware/latest/
+[docs-vmware-iso]: https://vmware.github.io/packer-plugin-vmware/latest/builders/iso/
+[docs-vmware-vmx]: https://vmware.github.io/packer-plugin-vmware/latest/builders/vmx/
 [golang-install]: https://golang.org/doc/install
 [releases-vmware-plugin]: https://github.com/vmware/packer-plugin-vmware/releases
 [packer-plugin-vsphere]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere

Taskfile.yml

@@ -59,3 +59,114 @@ tasks:
         packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
         ./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
         rm -r ".docs"
+
+  docs-deps:
+    desc: Install Zensical and mike into docs-site/.venv for local docs preview.
+    cmds:
+      - test -d docs-site/.venv || python3 -m venv docs-site/.venv
+      - docs-site/.venv/bin/pip install -r docs-site/requirements.txt
+
+  docs-prepare:
+    desc: Stage .web-docs into docs-site/.build/docs for Zensical.
+    cmds:
+      - ./docs-site/scripts/prepare-docs.sh
+
+  docs-test:
+    desc: Run all docs-site script unit tests.
+    cmds:
+      - ./docs-site/scripts/test/test-all.sh
+
+  docs-test-links:
+    desc: Run integration link rewrite tests for staged documentation.
+    cmds:
+      - ./docs-site/scripts/test/test-rewrite-integration-links.sh
+
+  docs-test-internal-links:
+    desc: Run internal link and anchor fix tests for staged documentation.
+    cmds:
+      - ./docs-site/scripts/test/test-fix-internal-links.sh
+
+  docs-test-admonitions:
+    desc: Run Material-to-Zensical admonition conversion tests.
+    cmds:
+      - ./docs-site/scripts/test/test-convert-admonitions.sh
+
+  docs-test-example-labels:
+    desc: Run HCL/JSON example label formatting tests.
+    cmds:
+      - ./docs-site/scripts/test/test-format-example-labels.sh
+
+  docs-test-group-example-tabs:
+    desc: Run HCL/JSON content tab grouping tests.
+    cmds:
+      - ./docs-site/scripts/test/test-group-example-tabs.sh
+
+  docs-test-normalize:
+    desc: Run staged markdown list spacing tests.
+    cmds:
+      - ./docs-site/scripts/test/test-normalize-list-spacing.sh
+
+  docs-test-strip-codegen:
+    desc: Run strip-codegen-comments tests.
+    cmds:
+      - ./docs-site/scripts/test/test-strip-codegen-comments.sh
+
+  docs-test-repair-fences:
+    desc: Run repair-code-fences tests.
+    cmds:
+      - ./docs-site/scripts/test/test-repair-code-fences.sh
+
+  docs-test-stage-markdown:
+    desc: Run staged markdown pipeline integration tests.
+    cmds:
+      - ./docs-site/scripts/test/test-stage-markdown.sh
+
+  docs-test-github-alerts:
+    desc: Run GitHub alert to admonition conversion tests.
+    cmds:
+      - ./docs-site/scripts/test/test-convert-github-alerts.sh
+
+  docs-build:
+    desc: Preview what documentation will look like at the next release (build).
+    deps: [generate, docs-deps, docs-prepare]
+    cmds:
+      - cd docs-site && ../docs-site/.venv/bin/zensical build --config-file zensical.build.toml
+
+  docs-serve:
+    desc: Preview what documentation will look like at the next release (live).
+    deps: [generate, docs-deps, docs-prepare]
+    cmds:
+      - cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
+
+  docs-serve-version:
+    desc: "Preview documentation from a released version."
+    deps: [docs-deps]
+    cmds:
+      - |
+        test -n "{{.VERSION}}" || (echo "VERSION is required" && exit 1)
+        rm -rf .web-docs
+        git checkout "v{{.VERSION}}" -- .web-docs
+        INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
+        cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
+
+  docs-serve-mike:
+    desc: Preview versioned documentation locally with mike (latest=last tag, development=branch name).
+    deps: [generate, docs-deps]
+    env:
+      MIKE_PREVIEW_VERSIONS: "{{.VERSIONS}}"
+    cmds:
+      - ./docs-site/scripts/mike-preview.sh
+
+  docs-serve-mike-only:
+    desc: Serve an existing local mike preview without redeploying.
+    deps: [docs-deps]
+    cmds:
+      - ./docs-site/scripts/mike-preview.sh --serve-only
+
+  docs-backfill:
+    desc: Backfill versioned documentation to GitHub Pages.
+    deps: [docs-deps]
+    env:
+      MIKE_BACKFILL_VERSIONS: "{{.VERSIONS}}"
+    cmds:
+      - ./docs-site/scripts/mike-backfill.sh {{.CLI_ARGS}}

docs-site/.gitignore

@@ -0,0 +1,4 @@
+.build/
+site/
+.venv/
+zensical.build.toml

docs-site/extra/builders/index.md

@@ -0,0 +1,11 @@
+---
+icon: lucide/toolbox
+title: Builders
+---
+
+# Builders
+
+Builders create machines and images on VMware desktop hypervisors, VMware
+Fusion Pro and VMware Workstation Pro.
+
+Select a builder from the navigation for the configuration reference.

docs-site/extra/community/code-of-conduct.md

@@ -0,0 +1,136 @@
+---
+title: Code of Conduct
+---
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[opensource@broadcom.com][enforcement]. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][cc], version
+[v2.1][cc-v2.1].
+
+Community Impact Guidelines were inspired by Mozilla's
+[Code of Conduct Enforcement][mozilla-coce] consequence ladder.
+
+For answers to common questions about this code of conduct, please refer to the
+[Frequently Asked Questions][cc-faq]. Translations are available in
+[additional languages][cc-translations].
+
+[cc]: https://www.contributor-covenant.org
+[cc-faq]: https://www.contributor-covenant.org/faq/
+[cc-translations]: https://www.contributor-covenant.org/translations/
+[cc-v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
+[enforcement]: mailto:opensource@broadcom.com?subject=Open%20Source%20Code%20of%20Conduct
+[mozilla-coce]: https://github.com/mozilla/inclusion/