Skip to content

Commit 2f233d9

Browse files
committed
docs: native project documentation (#522)
Adds native project documentation that will be rendered with Zensical and published through GitHub Pages. Signed-off-by: Ryan Johnson <ryan@tenthirtyam.org>
1 parent 73c91eb commit 2f233d9

61 files changed

Lines changed: 5375 additions & 5 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

Makefile

Lines changed: 69 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ COUNT?=1
66
TEST?=$(shell go list ./...)
77
HASHICORP_PACKER_PLUGIN_SDK_VERSION?=$(shell go list -m github.com/hashicorp/packer-plugin-sdk | cut -d " " -f2)
88

9-
.PHONY: dev
9+
.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
1010

1111
build:
1212
@go build -o ${BINARY}
@@ -18,7 +18,7 @@ dev:
1818
test:
1919
@go test -race -count $(COUNT) $(TEST) -timeout=3m
2020

21-
install-packer-sdc: # Install packer software development command.
21+
install-packer-sdc: ## Install packer sofware development command
2222
@go install github.com/hashicorp/packer-plugin-sdk/cmd/packer-sdc@${HASHICORP_PACKER_PLUGIN_SDK_VERSION}
2323

2424
plugin-check: install-packer-sdc build
@@ -29,7 +29,74 @@ testacc: dev
2929

3030
generate: install-packer-sdc
3131
@go generate ./...
32+
@go fmt ./...
3233
@rm -rf .docs
3334
@packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
3435
@./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
3536
@rm -r ".docs"
37+
38+
DOCS_VENV?=$(CURDIR)/docs-site/.venv
39+
DOCS_PYTHON=$(DOCS_VENV)/bin/python
40+
DOCS_PIP=$(DOCS_VENV)/bin/pip
41+
42+
docs-deps:
43+
@test -d "$(DOCS_VENV)" || python3 -m venv "$(DOCS_VENV)"
44+
@"$(DOCS_PIP)" install -r docs-site/requirements.txt
45+
46+
docs-prepare:
47+
@./docs-site/scripts/prepare-docs.sh
48+
49+
docs-test:
50+
@./docs-site/scripts/test/test-all.sh
51+
52+
docs-test-links:
53+
@./docs-site/scripts/test/test-rewrite-integration-links.sh
54+
55+
docs-test-internal-links:
56+
@./docs-site/scripts/test/test-fix-internal-links.sh
57+
58+
docs-test-admonitions:
59+
@./docs-site/scripts/test/test-convert-admonitions.sh
60+
61+
docs-test-example-labels:
62+
@./docs-site/scripts/test/test-format-example-labels.sh
63+
64+
docs-test-group-example-tabs:
65+
@./docs-site/scripts/test/test-group-example-tabs.sh
66+
67+
docs-test-normalize:
68+
@./docs-site/scripts/test/test-normalize-list-spacing.sh
69+
70+
docs-test-strip-codegen:
71+
@./docs-site/scripts/test/test-strip-codegen-comments.sh
72+
73+
docs-test-repair-fences:
74+
@./docs-site/scripts/test/test-repair-code-fences.sh
75+
76+
docs-test-stage-markdown:
77+
@./docs-site/scripts/test/test-stage-markdown.sh
78+
79+
docs-test-github-alerts:
80+
@./docs-site/scripts/test/test-convert-github-alerts.sh
81+
82+
docs-build: generate docs-deps docs-prepare
83+
@cd docs-site && "$(DOCS_VENV)/bin/zensical" build --config-file zensical.build.toml
84+
85+
docs-serve: generate docs-deps docs-prepare
86+
@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
87+
88+
docs-serve-version: docs-deps
89+
@test -n "$(VERSION)" || (echo "VERSION is required, e.g. make docs-serve-version VERSION=2.1.0" && exit 1)
90+
@rm -rf .web-docs
91+
@git checkout "v$(VERSION)" -- .web-docs
92+
@INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
93+
@cd docs-site && "$(DOCS_VENV)/bin/zensical" serve --config-file zensical.build.toml
94+
95+
docs-serve-mike: generate docs-deps
96+
@[ -z "$(VERSIONS)" ] || export MIKE_PREVIEW_VERSIONS="$(VERSIONS)"; ./docs-site/scripts/mike-preview.sh
97+
98+
docs-serve-mike-only: docs-deps
99+
@./docs-site/scripts/mike-preview.sh --serve-only
100+
101+
docs-backfill: docs-deps
102+
@./docs-site/scripts/mike-backfill.sh $(VERSIONS)

README.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -131,9 +131,9 @@ Licensed under the [Mozilla Public License, version 2.0][license].
131131
[desktop-hypervisors]: https://www.vmware.com/products/desktop-hypervisor/workstation-and-fusion
132132
[docs-packer-init]: https://developer.hashicorp.com/packer/docs/commands/init
133133
[docs-packer-plugin-install]: https://developer.hashicorp.com/packer/docs/plugins/install-plugins
134-
[docs-vmware-plugin]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/
135-
[docs-vmware-iso]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/components/builder/iso
136-
[docs-vmware-vmx]: https://developer.hashicorp.com/packer/integrations/vmware/vmware/latest/components/builder/vmx
134+
[docs-vmware-plugin]: https://vmware.github.io/packer-plugin-vmware/latest/
135+
[docs-vmware-iso]: https://vmware.github.io/packer-plugin-vmware/latest/builders/iso/
136+
[docs-vmware-vmx]: https://vmware.github.io/packer-plugin-vmware/latest/builders/vmx/
137137
[golang-install]: https://golang.org/doc/install
138138
[releases-vmware-plugin]: https://github.com/vmware/packer-plugin-vmware/releases
139139
[packer-plugin-vsphere]: https://developer.hashicorp.com/packer/integrations/vmware/vsphere

Taskfile.yml

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,114 @@ tasks:
5959
packer-sdc renderdocs -src "docs" -partials docs-partials/ -dst ".docs/"
6060
./.web-docs/scripts/compile-to-webdocs.sh "." ".docs" ".web-docs" "hashicorp"
6161
rm -r ".docs"
62+
63+
docs-deps:
64+
desc: Install Zensical and mike into docs-site/.venv for local docs preview.
65+
cmds:
66+
- test -d docs-site/.venv || python3 -m venv docs-site/.venv
67+
- docs-site/.venv/bin/pip install -r docs-site/requirements.txt
68+
69+
docs-prepare:
70+
desc: Stage .web-docs into docs-site/.build/docs for Zensical.
71+
cmds:
72+
- ./docs-site/scripts/prepare-docs.sh
73+
74+
docs-test:
75+
desc: Run all docs-site script unit tests.
76+
cmds:
77+
- ./docs-site/scripts/test/test-all.sh
78+
79+
docs-test-links:
80+
desc: Run integration link rewrite tests for staged documentation.
81+
cmds:
82+
- ./docs-site/scripts/test/test-rewrite-integration-links.sh
83+
84+
docs-test-internal-links:
85+
desc: Run internal link and anchor fix tests for staged documentation.
86+
cmds:
87+
- ./docs-site/scripts/test/test-fix-internal-links.sh
88+
89+
docs-test-admonitions:
90+
desc: Run Material-to-Zensical admonition conversion tests.
91+
cmds:
92+
- ./docs-site/scripts/test/test-convert-admonitions.sh
93+
94+
docs-test-example-labels:
95+
desc: Run HCL/JSON example label formatting tests.
96+
cmds:
97+
- ./docs-site/scripts/test/test-format-example-labels.sh
98+
99+
docs-test-group-example-tabs:
100+
desc: Run HCL/JSON content tab grouping tests.
101+
cmds:
102+
- ./docs-site/scripts/test/test-group-example-tabs.sh
103+
104+
docs-test-normalize:
105+
desc: Run staged markdown list spacing tests.
106+
cmds:
107+
- ./docs-site/scripts/test/test-normalize-list-spacing.sh
108+
109+
docs-test-strip-codegen:
110+
desc: Run strip-codegen-comments tests.
111+
cmds:
112+
- ./docs-site/scripts/test/test-strip-codegen-comments.sh
113+
114+
docs-test-repair-fences:
115+
desc: Run repair-code-fences tests.
116+
cmds:
117+
- ./docs-site/scripts/test/test-repair-code-fences.sh
118+
119+
docs-test-stage-markdown:
120+
desc: Run staged markdown pipeline integration tests.
121+
cmds:
122+
- ./docs-site/scripts/test/test-stage-markdown.sh
123+
124+
docs-test-github-alerts:
125+
desc: Run GitHub alert to admonition conversion tests.
126+
cmds:
127+
- ./docs-site/scripts/test/test-convert-github-alerts.sh
128+
129+
docs-build:
130+
desc: Preview what documentation will look like at the next release (build).
131+
deps: [generate, docs-deps, docs-prepare]
132+
cmds:
133+
- cd docs-site && ../docs-site/.venv/bin/zensical build --config-file zensical.build.toml
134+
135+
docs-serve:
136+
desc: Preview what documentation will look like at the next release (live).
137+
deps: [generate, docs-deps, docs-prepare]
138+
cmds:
139+
- cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
140+
141+
docs-serve-version:
142+
desc: "Preview documentation from a released version."
143+
deps: [docs-deps]
144+
cmds:
145+
- |
146+
test -n "{{.VERSION}}" || (echo "VERSION is required" && exit 1)
147+
rm -rf .web-docs
148+
git checkout "v{{.VERSION}}" -- .web-docs
149+
INCLUDE_EXTRA=true ./docs-site/scripts/prepare-docs.sh
150+
cd docs-site && ../docs-site/.venv/bin/zensical serve --config-file zensical.build.toml
151+
152+
docs-serve-mike:
153+
desc: Preview versioned documentation locally with mike (latest=last tag, development=branch name).
154+
deps: [generate, docs-deps]
155+
env:
156+
MIKE_PREVIEW_VERSIONS: "{{.VERSIONS}}"
157+
cmds:
158+
- ./docs-site/scripts/mike-preview.sh
159+
160+
docs-serve-mike-only:
161+
desc: Serve an existing local mike preview without redeploying.
162+
deps: [docs-deps]
163+
cmds:
164+
- ./docs-site/scripts/mike-preview.sh --serve-only
165+
166+
docs-backfill:
167+
desc: Backfill versioned documentation to GitHub Pages.
168+
deps: [docs-deps]
169+
env:
170+
MIKE_BACKFILL_VERSIONS: "{{.VERSIONS}}"
171+
cmds:
172+
- ./docs-site/scripts/mike-backfill.sh {{.CLI_ARGS}}

docs-site/.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.build/
2+
site/
3+
.venv/
4+
zensical.build.toml

docs-site/assets/header-logo.png

96.3 KB
Loading

docs-site/extra/builders/index.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
icon: lucide/toolbox
3+
title: Builders
4+
---
5+
6+
# Builders
7+
8+
Builders create machines and images on VMware desktop hypervisors, VMware
9+
Fusion Pro and VMware Workstation Pro.
10+
11+
Select a builder from the navigation for the configuration reference.
Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Code of Conduct
3+
---
4+
5+
# Contributor Covenant Code of Conduct
6+
7+
## Our Pledge
8+
9+
We as members, contributors, and leaders pledge to make participation in our
10+
community a harassment-free experience for everyone, regardless of age, body
11+
size, visible or invisible disability, ethnicity, sex characteristics, gender
12+
identity and expression, level of experience, education, socio-economic status,
13+
nationality, personal appearance, race, caste, color, religion, or sexual
14+
identity and orientation.
15+
16+
We pledge to act and interact in ways that contribute to an open, welcoming,
17+
diverse, inclusive, and healthy community.
18+
19+
## Our Standards
20+
21+
Examples of behavior that contributes to a positive environment for our
22+
community include:
23+
24+
* Demonstrating empathy and kindness toward other people
25+
* Being respectful of differing opinions, viewpoints, and experiences
26+
* Giving and gracefully accepting constructive feedback
27+
* Accepting responsibility and apologizing to those affected by our mistakes,
28+
and learning from the experience
29+
* Focusing on what is best not just for us as individuals, but for the overall
30+
community
31+
32+
Examples of unacceptable behavior include:
33+
34+
* The use of sexualized language or imagery, and sexual attention or advances of
35+
any kind
36+
* Trolling, insulting or derogatory comments, and personal or political attacks
37+
* Public or private harassment
38+
* Publishing others' private information, such as a physical or email address,
39+
without their explicit permission
40+
* Other conduct which could reasonably be considered inappropriate in a
41+
professional setting
42+
43+
## Enforcement Responsibilities
44+
45+
Community leaders are responsible for clarifying and enforcing our standards of
46+
acceptable behavior and will take appropriate and fair corrective action in
47+
response to any behavior that they deem inappropriate, threatening, offensive,
48+
or harmful.
49+
50+
Community leaders have the right and responsibility to remove, edit, or reject
51+
comments, commits, code, wiki edits, issues, and other contributions that are
52+
not aligned to this Code of Conduct, and will communicate reasons for moderation
53+
decisions when appropriate.
54+
55+
## Scope
56+
57+
This Code of Conduct applies within all community spaces, and also applies when
58+
an individual is officially representing the community in public spaces.
59+
Examples of representing our community include using an official email address,
60+
posting via an official social media account, or acting as an appointed
61+
representative at an online or offline event.
62+
63+
## Enforcement
64+
65+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
66+
reported to the community leaders responsible for enforcement at
67+
[opensource@broadcom.com][enforcement]. All complaints will be reviewed and
68+
investigated promptly and fairly.
69+
70+
All community leaders are obligated to respect the privacy and security of the
71+
reporter of any incident.
72+
73+
## Enforcement Guidelines
74+
75+
Community leaders will follow these Community Impact Guidelines in determining
76+
the consequences for any action they deem in violation of this Code of Conduct:
77+
78+
### 1. Correction
79+
80+
**Community Impact**: Use of inappropriate language or other behavior deemed
81+
unprofessional or unwelcome in the community.
82+
83+
**Consequence**: A private, written warning from community leaders, providing
84+
clarity around the nature of the violation and an explanation of why the
85+
behavior was inappropriate. A public apology may be requested.
86+
87+
### 2. Warning
88+
89+
**Community Impact**: A violation through a single incident or series of
90+
actions.
91+
92+
**Consequence**: A warning with consequences for continued behavior. No
93+
interaction with the people involved, including unsolicited interaction with
94+
those enforcing the Code of Conduct, for a specified period of time. This
95+
includes avoiding interactions in community spaces as well as external channels
96+
like social media. Violating these terms may lead to a temporary or permanent
97+
ban.
98+
99+
### 3. Temporary Ban
100+
101+
**Community Impact**: A serious violation of community standards, including
102+
sustained inappropriate behavior.
103+
104+
**Consequence**: A temporary ban from any sort of interaction or public
105+
communication with the community for a specified period of time. No public or
106+
private interaction with the people involved, including unsolicited interaction
107+
with those enforcing the Code of Conduct, is allowed during this period.
108+
Violating these terms may lead to a permanent ban.
109+
110+
### 4. Permanent Ban
111+
112+
**Community Impact**: Demonstrating a pattern of violation of community
113+
standards, including sustained inappropriate behavior, harassment of an
114+
individual, or aggression toward or disparagement of classes of individuals.
115+
116+
**Consequence**: A permanent ban from any sort of public interaction within the
117+
community.
118+
119+
## Attribution
120+
121+
This Code of Conduct is adapted from the [Contributor Covenant][cc], version
122+
[v2.1][cc-v2.1].
123+
124+
Community Impact Guidelines were inspired by Mozilla's
125+
[Code of Conduct Enforcement][mozilla-coce] consequence ladder.
126+
127+
For answers to common questions about this code of conduct, please refer to the
128+
[Frequently Asked Questions][cc-faq]. Translations are available in
129+
[additional languages][cc-translations].
130+
131+
[cc]: https://www.contributor-covenant.org
132+
[cc-faq]: https://www.contributor-covenant.org/faq/
133+
[cc-translations]: https://www.contributor-covenant.org/translations/
134+
[cc-v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
135+
[enforcement]: mailto:opensource@broadcom.com?subject=Open%20Source%20Code%20of%20Conduct
136+
[mozilla-coce]: https://github.com/mozilla/inclusion/

0 commit comments

Comments
 (0)