Skip to content

Commit b0a3ce9

Browse files
adambkaplanadambkaplan
committed
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]>
1 parent cbc78b7 commit b0a3ce9

File tree

13 files changed

+1427
-2
lines changed

13 files changed

+1427
-2
lines changed

‎.gitignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,11 @@ resources/
66
public/
77
.hugo_build.lock
88

9+
# Supporting tools
10+
bin/
11+
12+
# API Generation
13+
api-gen/build/
14+
915
# IDEs
1016
.vscode

‎CONTRIBUTING.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Website Contributing Guide
2+
3+
Do you want to contribute to Shipwright's documentation, or publish a blog post about Shipwright?
4+
You have come to the right place!
5+
6+
## Before You Begin
7+
8+
- Review the overall project [contributor guide](https://github.com/shipwright-io/.github/blob/main/CONTRIBUTING.md)
9+
and [code of conduct](https://github.com/shipwright-io/.github/blob/main/CODE_OF_CONDUCT.md).
10+
- Set up your computer to contribute content to the website. Review the "Getting Started" section
11+
in the [README](README.md) for details.
12+
13+
## Adding Content
14+
15+
There are two main forms of content on the website - documentation and blog posts.
16+
17+
We use the [Hugo](https://gohugo.io) framework to generate the website content, which supports
18+
internationalization. At present we publish content only in English, located in the `content/en`
19+
directory.
20+
21+
### Adding Documentation Content
22+
23+
Documentation content can come in various forms, but is directly related to the features and
24+
functionality of Shipwright's projects. This content is located in the `content/en/docs` directory.
25+
26+
API reference documentation - located in `content/en/docs/ref` - should not be edited by hand. This
27+
content should only be generated by running the `gen-api-docs` Makefile target:
28+
29+
```sh
30+
make gen-api-docs
31+
```
32+
33+
### Adding Blog Posts
34+
35+
Blog post content should be located in the `content/en/blog/posts` directory.
36+
37+
Release notes may also be published in the `content/en/blog/releases` directory.

‎Makefile

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,4 +37,19 @@ serve: ## serve the content locally for testing
3737

3838
.PHONY: serve-preview
3939
serve-preview: ## serve the preview content locally for testing
40-
hugo -t docsy server -F
40+
hugo -t docsy server -F
41+
42+
.PHONY: bin-dir
43+
bin-dir: ## Creates a local "bin" directory for helper applications.
44+
@mkdir ./bin || true
45+
46+
.PHONY: crd-ref-docs
47+
crd-ref-docs: bin-dir ## install crd-ref-docs tool
48+
GOBIN=$(shell pwd)/bin go install github.com/elastic/[email protected]
49+
50+
BUILD_REPO ?= "https://github.com/shipwright-io/build.git"
51+
BUILD_VERSION ?= "v0.15.0"
52+
53+
.PHONY: gen-api-docs
54+
gen-api-docs: crd-ref-docs ## generate API reference documentation
55+
BUILD_REPO=$(BUILD_REPO) BUILD_VERSION=$(BUILD_VERSION) ./hack/gen-api-docs.sh

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ Then install any additional dependencies by running `make install`
3030
To run the website locally, use Hugo's `server` command:
3131

3232
```bash
33-
$ hugo server
33+
$ hugo -t docsy server
3434
```
3535

3636
## Contributing

‎api-gen/build.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
processor:
2+
ignoreFields:
3+
- "TypeMeta$"
4+
render:
5+
kubernetesVersion: 1.30

‎api-gen/templates/markdown/gv_details.tpl

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{{- define "gvDetails" -}}
2+
{{- $gv := . -}}
3+
4+
# {{ $gv.GroupVersionString }}
5+
6+
{{ $gv.Doc }}
7+
8+
{{- if len $gv.Kinds }}
9+
## Resource Types
10+
{{- range $gv.SortedKinds }}
11+
- {{ $gv.TypeForKind . | markdownRenderTypeLink }}
12+
{{- end }}
13+
{{ end }}
14+
15+
{{ range $gv.SortedTypes }}
16+
{{ template "type" . }}
17+
{{ end }}
18+
19+
{{- end -}}

‎api-gen/templates/markdown/gv_list.tpl

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{{- define "gvList" -}}
2+
{{- $groupVersions := . -}}
3+
4+
---
5+
title: {{env "API_GROUP"}} Resources
6+
weight: {{env "API_WEIGHT"}}
7+
---
8+
9+
# Packages
10+
{{- range $groupVersions }}
11+
- {{ markdownRenderGVLink . }}
12+
{{- end }}
13+
14+
{{ range $groupVersions }}
15+
{{ template "gvDetails" . }}
16+
{{ end }}
17+
18+
{{- end -}}

‎api-gen/templates/markdown/type.tpl

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{{- define "type" -}}
2+
{{- $type := . -}}
3+
{{- if markdownShouldRenderType $type -}}
4+
5+
### {{ $type.Name }}
6+
7+
{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }}
8+
9+
{{ $type.Doc }}
10+
11+
{{ if $type.Validation -}}
12+
_Validation:_
13+
{{- range $type.Validation }}
14+
- {{ . }}
15+
{{- end }}
16+
{{- end }}
17+
18+
{{ if $type.References -}}
19+
_Appears in:_
20+
{{- range $type.SortedReferences }}
21+
- {{ markdownRenderTypeLink . }}
22+
{{- end }}
23+
{{- end }}
24+
25+
{{ if $type.Members -}}
26+
| Field | Description | Default | Validation |
27+
| --- | --- | --- | --- |
28+
{{ if $type.GVK -}}
29+
| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` | | |
30+
| `kind` _string_ | `{{ $type.GVK.Kind }}` | | |
31+
{{ end -}}
32+
33+
{{ range $type.Members -}}
34+
| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | {{ markdownRenderDefault .Default }} | {{ range .Validation -}} {{ markdownRenderFieldDoc . }} <br />{{ end }} |
35+
{{ end -}}
36+
37+
{{ end -}}
38+
39+
{{ if $type.EnumValues -}}
40+
| Field | Description |
41+
| --- | --- |
42+
{{ range $type.EnumValues -}}
43+
| `{{ .Name }}` | {{ markdownRenderFieldDoc .Doc }} |
44+
{{ end -}}
45+
{{ end -}}
46+
47+
48+
{{- end -}}
49+
{{- end -}}

‎api-gen/templates/markdown/type_members.tpl

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{{- define "type_members" -}}
2+
{{- $field := . -}}
3+
{{- if eq $field.Name "metadata" -}}
4+
Refer to Kubernetes API documentation for fields of `metadata`.
5+
{{- else -}}
6+
{{ markdownRenderFieldDoc $field.Doc }}
7+
{{- end -}}
8+
{{- end -}}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Reference"
3+
weight: 30
4+
---
5+
6+
This section contains reference documentation.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: API Reference
3+
weight: 10
4+
---

0 commit comments

Comments
 (0)