Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Agones Kubernetes API docs generator #645

Merged
merged 1 commit into from
Mar 25, 2019
Merged

Add Agones Kubernetes API docs generator #645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion build/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -352,7 +352,7 @@ The second step is to prepare your cluster for the Agones deployments. Run `make

Now you're ready to begin the development/test cycle:
- `make build` will build Agones
- `make test` will run local tests
- `make test` will run local tests, which includes `site-test` target
- `make push` will push the Agones images to your image repository
- `make test-e2e` will run end-to-end tests in your cluster
- `make install` will install/upgrade Agones into your cluster
Expand Down Expand Up @@ -412,6 +412,18 @@ Build the cpp sdk static and dynamic libraries (linux libraries only)
#### `make test`
Run the linter and tests

#### `make site-server`
Generate `https://agones.dev` website locally and host on `http://localhost:1313`

#### `make site-test`
Check the links in website

#### `make gen-api-docs`
Generate Agones CRD reference documentation [Agones CRD API reference](../site/content/en/docs/Reference/agones_crd_api_reference.html). Set `feature` shortcode with proper version automatically

#### `make test-gen-api-docs`
Verifies that there is no changes in generated [Agones CRD API reference](../site/content/en/docs/Reference/agones_crd_api_reference.html) compared to the current one (useful for CI)

#### `make push`
Pushes all built images up to the `$(REGISTRY)`

Expand Down
5 changes: 5 additions & 0 deletions build/build-image/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,11 @@ RUN mkdir /tmp/hugo && \
RUN curl -sL https://deb.nodesource.com/setup_11.x | bash - && \
apt-get install -y nodejs

# install API reference docs generator
RUN mkdir -p /go/src/github.com/ahmetb && \
cd /go/src/github.com/ahmetb && git clone https://github.com/ahmetb/gen-crd-api-reference-docs && \
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should probably pin to a commit here.
Given there's a copy of the template in this repo, I don't want to accidentally break the downstream.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @ahmetb for the review. I was thinking about that, will provide an update in a separate PR.

cd ./gen-crd-api-reference-docs && go build

# html checker
RUN mkdir /tmp/htmltest && \
wget -O /tmp/htmltest/htmltest.tar.gz https://github.com/wjdp/htmltest/releases/download/v0.10.1/htmltest_0.10.1_linux_amd64.tar.gz && \
Expand Down
22 changes: 20 additions & 2 deletions build/includes/website.mk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
#
# Website targets
#

# generate the latest website
site-server: ARGS ?=-F
site-server: ENV ?= RELEASE_VERSION="$(base_version)" RELEASE_BRANCH=master
Expand Down Expand Up @@ -59,6 +59,24 @@ site-deploy-preview: site-static-preview

site-test:
# generate actual html and run test against - provides a more accurate tests
$(MAKE) test-gen-api-docs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a good answer for this - but because the website works off master - if we change our CRD data structures, that will change the website as well, and be out of sync until next release.

Only idea I've got - that in the advent of that happening - rename the old page and put an expiryDate of the next release in the toml.... but how would we get a publishDate in the new one, and still pass tests?

I'm just thinking out loud here, but any ideas?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tried to use custom short code in front-matter and it seems that variables are not supported there.
So currently I am thinking of combining one full generated html with expiryVersion shortcode. And new one with publishVersion shortcode in the same file.
And during test just compare the second half with publishVersion. And during release move bottom half to the top and generate new one at the bottom.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds fancy - but makes sense to me! I assume you can make that work? 😄

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have updated gen-api-docs.sh script. It now handles base_version environment variable.
What it does is get all lines before publishVersion line. Then extract what in the middle of this feature shortcode. Compares with what was generated if diff then do version compare.
Then set expiryVersion of old part with new base_version fresh generated doc now have new publishVersion.

$(MAKE) site-static-preview
docker run --rm -t -e "TERM=xterm-256color" $(common_mounts) $(DOCKER_RUN_ARGS) $(build_tag) bash -c \
"mkdir -p /tmp/website && cp -r $(mount_path)/site/public /tmp/website/site && htmltest -c $(mount_path)/site/htmltest.yaml /tmp/website"
"mkdir -p /tmp/website && cp -r $(mount_path)/site/public /tmp/website/site && htmltest -c $(mount_path)/site/htmltest.yaml /tmp/website"

# Path to a file and docker command
REL_PATH := content/en/docs/Reference/agones_crd_api_reference.html
GEN_API_DOCS := docker run -e FILE="$(mount_path)/site/$(REL_PATH)" -e VERSION=${base_version} --rm -i $(common_mounts) $(build_tag) bash -c "/go/src/agones.dev/agones/site/gen-api-docs.sh"

# generate Agones CRD reference docs
gen-api-docs: ensure-build-image
$(GEN_API_DOCS)

# test generated Agones CRD reference docs
test-gen-api-docs: expected_docs := $(site_path)/$(REL_PATH)
test-gen-api-docs: ensure-build-image
cp $(expected_docs) /tmp/generated.html
sort /tmp/generated.html > /tmp/generated.html.sorted
$(GEN_API_DOCS)
sort $(expected_docs) > /tmp/result.sorted
diff -bB /tmp/result.sorted /tmp/generated.html.sorted
46 changes: 46 additions & 0 deletions site/assets/templates/pkg.tpl
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
{{ define "packages" }}

{{ with .packages}}
<p>Packages:</p>
<ul>
{{ range . }}
<li>
<a href="#{{- packageDisplayName . -}}">{{ packageDisplayName . }}</a>
</li>
{{ end }}
</ul>
{{ end}}

{{ range .packages }}
<h2 id="{{- packageDisplayName . -}}">
{{- packageDisplayName . -}}
</h2>

{{ with .DocComments }}
<p>
{{ safe (renderComments .) }}
</p>
{{ end }}

Resource Types:
<ul>
{{- range (visibleTypes (sortedTypes .Types)) -}}
{{ if isExportedType . -}}
<li>
<a href="#{{ typeIdentifier . }}">{{ typeIdentifier . }}</a>
</li>
{{- end }}
{{- end -}}
</ul>

{{ range (visibleTypes (sortedTypes .Types))}}
{{ template "type" . }}
{{ end }}
<hr/>
{{ end }}

<p><em>
Generated with <code>gen-crd-api-reference-docs</code>.
</em></p>

{{ end }}
6 changes: 5 additions & 1 deletion site/content/en/docs/Guides/access-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,11 @@ description: >
---

Installing Agones creates several [Custom Resource Definitions (CRD)](https://kubernetes.io/docs/concepts/api-extension/custom-resources),
which can be accessed and manipulated through the Kubernetes API.
which can be accessed and manipulated through the Kubernetes API.

{{% feature publishVersion="0.9.0" %}}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think the CRDs have changed - could we publish this all now? (0.8.0?)

Copy link
Collaborator Author

@aLekSer aLekSer Mar 25, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated publishVersion, test still pass.

The detailed list of Agones CRDs with their parameters could be found here - [Agones CRD API Reference](../../reference/agones_crd_api_reference/).
{{% /feature %}}

Kubernetes has multiple [client libraries](https://kubernetes.io/docs/reference/using-api/client-libraries/), however,
at time of writing, only
Expand Down
Loading