feat: Generate Build API Reference Docs

Auto-generate API reference docs from Go comments. This is considered
best practice.

- Utilize elastic/crd-ref-docs tool. This is much easier to use than
  the Kubernetes CRD docs stack.
- Copy markdown templates from elastic/crd-ref-docs, so they can be
  customized later.
- Use Makefile to run script generating docs from Shipwright build
  project.
- Added a contributor guide to fix a broken link, and describe how to
  generate API docs to future contributors.

Documentation was generated from the v0.15.0 release tag.

Signed-off-by: Adam Kaplan <[email protected]>

.gitignore

@@ -6,5 +6,11 @@ resources/
 public/
 .hugo_build.lock
 
+# Supporting tools
+bin/
+
+# API Generation
+api-gen/build/
+
 # IDEs
 .vscode

CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Website Contributing Guide
+
+Do you want to contribute to Shipwright's documentation, or publish a blog post about Shipwright?
+You have come to the right place!
+
+## Before You Begin
+
+- Review the overall project [contributor guide](https://github.com/shipwright-io/.github/blob/main/CONTRIBUTING.md)
+  and [code of conduct](https://github.com/shipwright-io/.github/blob/main/CODE_OF_CONDUCT.md).
+- Set up your computer to contribute content to the website. Review the "Getting Started" section
+  in the [README](README.md) for details.
+
+## Adding Content
+
+There are two main forms of content on the website - documentation and blog posts.
+
+We use the [Hugo](https://gohugo.io) framework to generate the website content, which supports
+internationalization. At present we publish content only in English, located in the `content/en`
+directory.
+
+### Adding Documentation Content
+
+Documentation content can come in various forms, but is directly related to the features and
+functionality of Shipwright's projects. This content is located in the `content/en/docs` directory.
+
+API reference documentation - located in `content/en/docs/ref` - should not be edited by hand. This
+content should only be generated by running the `gen-api-docs` Makefile target:
+
+```sh
+make gen-api-docs
+```
+
+### Adding Blog Posts
+
+Blog post content should be located in the `content/en/blog/posts` directory.
+
+Release notes may also be published in the `content/en/blog/releases` directory.

Makefile

@@ -37,4 +37,19 @@ serve: ## serve the content locally for testing
 
 .PHONY: serve-preview
 serve-preview: ## serve the preview content locally for testing
-	hugo -t docsy server -F
+	hugo -t docsy server -F
+
+.PHONY: bin-dir
+bin-dir: ## Creates a local "bin" directory for helper applications.
+	@mkdir ./bin || true
+
+.PHONY: crd-ref-docs
+crd-ref-docs: bin-dir ## install crd-ref-docs tool
+	GOBIN=$(shell pwd)/bin go install github.com/elastic/[email protected]
+
+BUILD_REPO ?= "https://github.com/shipwright-io/build.git"
+BUILD_VERSION ?= "v0.15.0"
+
+.PHONY: gen-api-docs
+gen-api-docs: crd-ref-docs ## generate API reference documentation
+	BUILD_REPO=$(BUILD_REPO) BUILD_VERSION=$(BUILD_VERSION) ./hack/gen-api-docs.sh

README.md

@@ -30,7 +30,7 @@ Then install any additional dependencies by running `make install`
 To run the website locally, use Hugo's `server` command:
 
 ```bash
-$ hugo server
+$ hugo -t docsy server
 ```
 
 ## Contributing

api-gen/build.yaml

@@ -0,0 +1,5 @@
+processor:
+  ignoreFields:
+    - "TypeMeta$"
+render:
+  kubernetesVersion: 1.30

api-gen/templates/markdown/gv_details.tpl

@@ -0,0 +1,19 @@
+{{- define "gvDetails" -}}
+{{- $gv := . -}}
+
+# {{ $gv.GroupVersionString }}
+
+{{ $gv.Doc }}
+
+{{- if len $gv.Kinds  }}
+## Resource Types
+{{- range $gv.SortedKinds }}
+- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
+{{- end }}
+{{ end }}
+
+{{ range $gv.SortedTypes }}
+{{ template "type" . }}
+{{ end }}
+
+{{- end -}}

api-gen/templates/markdown/gv_list.tpl

@@ -0,0 +1,18 @@
+{{- define "gvList" -}}
+{{- $groupVersions := . -}}
+
+---
+title: {{env "API_GROUP"}} Resources
+weight: {{env "API_WEIGHT"}}
+---
+
+# Packages
+{{- range $groupVersions }}
+- {{ markdownRenderGVLink . }}
+{{- end }}
+
+{{ range $groupVersions }}
+{{ template "gvDetails" . }}
+{{ end }}
+
+{{- end -}}

api-gen/templates/markdown/type.tpl

@@ -0,0 +1,49 @@
+{{- define "type" -}}
+{{- $type := . -}}
+{{- if markdownShouldRenderType $type -}}
+
+### {{ $type.Name }}
+
+{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType  }}_{{ end }}
+
+{{ $type.Doc }}
+
+{{ if $type.Validation -}}
+_Validation:_
+{{- range $type.Validation }}
+- {{ . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.References -}}
+_Appears in:_
+{{- range $type.SortedReferences }}
+- {{ markdownRenderTypeLink . }}
+{{- end }}
+{{- end }}
+
+{{ if $type.Members -}}
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+{{ if $type.GVK -}}
+| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
+| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
+{{ end -}}
+
+{{ range $type.Members -}}
+| `{{ .Name  }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
+{{ end -}}
+
+{{ end -}}
+
+{{ if $type.EnumValues -}} 
+| Field | Description |
+| --- | --- |
+{{ range $type.EnumValues -}}
+| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
+{{ end -}}
+{{ end -}}
+
+
+{{- end -}}
+{{- end -}}

api-gen/templates/markdown/type_members.tpl

@@ -0,0 +1,8 @@
+{{- define "type_members" -}}
+{{- $field := . -}}
+{{- if eq $field.Name "metadata" -}}
+Refer to Kubernetes API documentation for fields of `metadata`.
+{{- else -}}
+{{ markdownRenderFieldDoc $field.Doc }}
+{{- end -}}
+{{- end -}}

content/en/docs/ref/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Reference"
+weight: 30
+---
+
+This section contains reference documentation.

content/en/docs/ref/api/_index.md

@@ -0,0 +1,4 @@
+---
+title: API Reference
+weight: 10
+---