Skip to content

Adds API Docs Tooling#980

Merged
zirain merged 1 commit intoenvoyproxy:mainfrom
danehans:api_docs
Feb 9, 2023
Merged

Adds API Docs Tooling#980
zirain merged 1 commit intoenvoyproxy:mainfrom
danehans:api_docs

Conversation

@danehans
Copy link
Copy Markdown
Contributor

@danehans danehans commented Feb 4, 2023

Uses github.com/elastic/crd-ref-docs to generate API docs.

Fixes #965

Signed-off-by: danehans daneyonhansen@gmail.com

@danehans danehans requested a review from a team as a code owner February 4, 2023 00:21
@danehans
Copy link
Copy Markdown
Contributor Author

danehans commented Feb 4, 2023

I'm not 100% happy with the generated output, but this can serve as a starting point for the API docs.

@danehans danehans added this to the 0.3.0 milestone Feb 4, 2023
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Feb 4, 2023

Codecov Report

Merging #980 (fc37c57) into main (7639637) will decrease coverage by 0.07%.
The diff coverage is n/a.

📣 This organization is not using Codecov’s GitHub App Integration. We recommend you install it so Codecov can continue to function properly for your repositories. Learn more

@@            Coverage Diff             @@
##             main     #980      +/-   ##
==========================================
- Coverage   62.19%   62.12%   -0.07%     
==========================================
  Files          55       55              
  Lines        8779     8779              
==========================================
- Hits         5460     5454       -6     
- Misses       2951     2955       +4     
- Partials      368      370       +2
Impacted Files Coverage Δ
internal/provider/kubernetes/helpers.go 81.08% <0.00%> (-0.68%) ⬇️
internal/provider/kubernetes/controller.go 49.77% <0.00%> (-0.57%) ⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

@danehans danehans force-pushed the api_docs branch 2 times, most recently from 432e699 to 777cd4b Compare February 4, 2023 00:28
arkodg
arkodg previously approved these changes Feb 4, 2023
View reviewed changes
Copy link
Copy Markdown
Contributor

@arkodg arkodg left a comment

Choose a reason for hiding this comment

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

thanks for building this
the code looks fine, SGTM
here's another tool https://github.com/ahmetb/gen-crd-api-reference-docs that seems to be used by upstream https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/api-docs/generate.sh to generate api docs

@zirain
Copy link
Copy Markdown
Member

zirain commented Feb 4, 2023

thanks for building this the code looks fine, SGTM here's another tool https://github.com/ahmetb/gen-crd-api-reference-docs that seems to be used by upstream https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/api-docs/generate.sh to generate api docs

I tried with that last night, almost completed.

@danehans
Copy link
Copy Markdown
Contributor Author

danehans commented Feb 6, 2023

here's another tool https://github.com/ahmetb/gen-crd-api-reference-docs that seems to be used by upstream https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/api-docs/generate.sh to generate api docs

@arkodg I looked at ^ tool first but settled on crd-reference-documentation-generator since it seemed better supported and for these reasons. Although the generator is fast, I'm not too impressed by the outcome and I still don't understand why the generator is having issues with the HeaderMatch type.

@arkodg
Copy link
Copy Markdown
Contributor

arkodg commented Feb 6, 2023

here's another tool https://github.com/ahmetb/gen-crd-api-reference-docs that seems to be used by upstream https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/api-docs/generate.sh to generate api docs

@arkodg I looked at ^ tool first but settled on crd-reference-documentation-generator since it seemed better supported and for these reasons. Although the generator is fast, I'm not too impressed by the outcome and I still don't understand why the generator is having issues with the HeaderMatch type.

SGTM thanks for explaining, the lint error is due to https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md051---link-fragments-should-be-valid
and it looks like there should be a valid title for headermatch which doesnt exist

@zirain
Copy link
Copy Markdown
Member

zirain commented Feb 7, 2023

FYI, https://github.com/ahmetb/gen-crd-api-reference-docs generate a bad output when using type like map[LogComponent]LogLevel

@danehans
Copy link
Copy Markdown
Contributor Author

danehans commented Feb 7, 2023

@zirain thanks for the information. The lint issue with this PR is due to the HeaderMatch struct which is not a map.

@zirain
Copy link
Copy Markdown
Member

zirain commented Feb 8, 2023

send a PR with my work on api doc #996

Xunzhuo
Xunzhuo previously approved these changes Feb 8, 2023
View reviewed changes
Copy link
Copy Markdown
Member

@Xunzhuo Xunzhuo left a comment

Choose a reason for hiding this comment

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

I prefer this one, LGTM, but need to resolve this lint error, or just try to ignore it.

zirain
zirain previously approved these changes Feb 9, 2023
View reviewed changes
Copy link
Copy Markdown
Member

@zirain zirain left a comment

Choose a reason for hiding this comment

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

this one is better than #996

@zirain zirain mentioned this pull request Feb 9, 2023
Closed
@danehans
Adds API Docs Tooling
8fcaeaa 
Signed-off-by: danehans <daneyonhansen@gmail.com>
@danehans danehans dismissed stale reviews from zirain, Xunzhuo, and arkodg via 8fcaeaa February 9, 2023 02:01
@zirain
Copy link
Copy Markdown
Member

zirain commented Feb 9, 2023

/doc

@zirain
Copy link
Copy Markdown
Member

zirain commented Feb 9, 2023

image

this part is better!

zirain
zirain approved these changes Feb 9, 2023
View reviewed changes
Copy link
Copy Markdown
Member

@zirain zirain left a comment

Choose a reason for hiding this comment

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

lgtm, thanks!

@zirain zirain merged commit d5a5b25 into envoyproxy:main Feb 9, 2023
arkodg pushed a commit to arkodg/gateway that referenced this pull request Feb 10, 2023
@danehans
Adds API Docs Tooling (envoyproxy#980)
43a2e16 
Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit d5a5b25)
Signed-off-by: Arko Dasgupta <arko@tetrate.io>
Xunzhuo pushed a commit to Xunzhuo/gateway that referenced this pull request Feb 10, 2023
@danehans @Xunzhuo
Adds API Docs Tooling (envoyproxy#980)
fedf160 
Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit d5a5b25)
Signed-off-by: bitliu <bitliu@tencent.com>
Xunzhuo added a commit that referenced this pull request Feb 10, 2023
@Xunzhuo @arkodg
@dependabot @danehans @jcheld
cherry-pick: commits from main to v0.3.0 (#1027)
f735041 
* fix: incorrect command in release schedule (#973)

* chore: rename release-notes v0.3.0-rc1.yaml to v0.3.0-rc.1.yaml

Signed-off-by: bitliu <bitliu@tencent.com>

* fix: incorrect command in release schedule

Signed-off-by: bitliu <bitliu@tencent.com>

---------

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit 7639637)
Signed-off-by: bitliu <bitliu@tencent.com>

* xds: Deprecated http2_protocol_options (#974)

* xds: Deprecated http2_protocol_options

Signed-off-by: hejianpeng <hejianpeng2@huawei.com>
(cherry picked from commit 4a04915)
Signed-off-by: bitliu <bitliu@tencent.com>

* Use HTTP1.1 to connect to upstream jwks endpoint (#977)

Use HTTP1.1 to connec to upstream jwks endpoint

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 82e7672)
Signed-off-by: bitliu <bitliu@tencent.com>

* Add status in HTTPRoute when Ratelimit is disabled (#982)

* Add status in HTTPRoute when Ratelimit is disabled

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit ebb902b)
Signed-off-by: bitliu <bitliu@tencent.com>

* build(deps): bump actions/deploy-pages from 1.2.3 to 1.2.4 (#984)

Bumps [actions/deploy-pages](https://github.com/actions/deploy-pages) from 1.2.3 to 1.2.4.
- [Release notes](https://github.com/actions/deploy-pages/releases)
- [Commits](actions/deploy-pages@v1.2.3...v1.2.4)

---
updated-dependencies:
- dependency-name: actions/deploy-pages
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
(cherry picked from commit 1bea44e)
Signed-off-by: bitliu <bitliu@tencent.com>

* build(deps): bump sigs.k8s.io/controller-runtime from 0.14.2 to 0.14.4 (#985)

Bumps [sigs.k8s.io/controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) from 0.14.2 to 0.14.4.
- [Release notes](https://github.com/kubernetes-sigs/controller-runtime/releases)
- [Changelog](https://github.com/kubernetes-sigs/controller-runtime/blob/master/RELEASE.md)
- [Commits](kubernetes-sigs/controller-runtime@v0.14.2...v0.14.4)

---
updated-dependencies:
- dependency-name: sigs.k8s.io/controller-runtime
  dependency-type: direct:production
  update-type: version-update:semver-patch
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
(cherry picked from commit fadc142)
Signed-off-by: bitliu <bitliu@tencent.com>

* fix function names for RL Infra (#976)

The create and delete function names were incorrectly swapped.

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 265c419)
Signed-off-by: bitliu <bitliu@tencent.com>

* Add docs for GRPCRoute (#969)

* Add docs for GRPCRoute

Fixes: #642

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 3516d10)
Signed-off-by: bitliu <bitliu@tencent.com>

* align wellknown package (#981)

Signed-off-by: hejianpeng <hejianpeng2@huawei.com>
(cherry picked from commit eec43d2)
Signed-off-by: bitliu <bitliu@tencent.com>

* Plug in rate limit service URL into xds cluster (#983)

* Plug in rate limit service URL into xds cluster

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

* more guardrails

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

* set to grpcPort and pin image

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 1b26380)
Signed-off-by: bitliu <bitliu@tencent.com>

* Adds JWT Authn User Docs (#991)

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit 2a431c1)
Signed-off-by: bitliu <bitliu@tencent.com>

* user docs for global rate limit (#989)

* user docs for global rate limit

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit ab47d2e)
Signed-off-by: bitliu <bitliu@tencent.com>

* docs: add ref to global ratelimit (#999)

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit 5115330)
Signed-off-by: bitliu <bitliu@tencent.com>

* Update gateway-api to v0.6.1 (#1003)

https://github.com/kubernetes-sigs/gateway-api/releases/tag/v0.6.1

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit d01daec)
Signed-off-by: bitliu <bitliu@tencent.com>

* Add GRPCRoute to SupportedKinds (#990)

Fixes: #950

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit beb6eae)
Signed-off-by: bitliu <bitliu@tencent.com>

* Use `path_separated_prefix` Route match (#1004)

* Use `path_separated_prefix` Route match

We were using `prefix` Route match in xds for
the `PathPrefix` Gateway API match defined here
https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1beta1.HTTPPathMatch

The match translates to a `path_separated_prefix` instead
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#config-route-v3-routematch

This should fix the `HTTPRouteMatching` conformance test where requests
with `/v2example` should match `/` and not `/v2`

Fixes: #995

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

* rewrite empty match case

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

* use prefix match for `/`

Signed-off-by: Arko Dasgupta <arko@tetrate.io>

---------

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit c26d894)
Signed-off-by: bitliu <bitliu@tencent.com>

* Adds API Docs Tooling (#980)

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit d5a5b25)
Signed-off-by: bitliu <bitliu@tencent.com>

* Updates API godocs for improved markdown rendering (#1010)

Updates API godocs for improved html rendering

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit b43574a)
Signed-off-by: bitliu <bitliu@tencent.com>

* chore: bump testdata to gwapi v0.6.1 (#1011)

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit f39b025)
Signed-off-by: bitliu <bitliu@tencent.com>

* conformance: enable GatewayClassObservedGenerationBump (#896)

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit b668002)
Signed-off-by: bitliu <bitliu@tencent.com>

* Run all conformance tests except redirect tests (#1014)

Redirect tests are failing due to a possible issue
with the way upstream conformance tests have made assumptions
Skipping them for now until below issues are resolved

#992
#993
#994

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 38a6ddd)
Signed-off-by: bitliu <bitliu@tencent.com>

* remove empty route error check in auth xds logic (#1019)

the Xds translator should not error out when the IR routes
are empty

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 821b7d5)
Signed-off-by: bitliu <bitliu@tencent.com>

* Removes GatewayObservedGenerationBump and HTTPRouteObservedGenerationBump Tests (#1021)

(cherry picked from commit d016a66)
Signed-off-by: bitliu <bitliu@tencent.com>

* Add Gateway API support doc (#1017)

add gatewayapi support doc

Signed-off-by: AliceProxy <alicewasko@datawire.io>
(cherry picked from commit a33e627)
Signed-off-by: bitliu <bitliu@tencent.com>

* Adds Cherry-Pick Steps to Release Doc (#1018)

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit 3d8120e)
Signed-off-by: bitliu <bitliu@tencent.com>

* update to validate 1.26 (#1020)

* update to validate 1.26

Signed-off-by: Held, Jarad <jaradheld@gmail.com>

* correct the tag for kubernetes version for comformance tests

Signed-off-by: Held, Jarad <jaradheld@gmail.com>

---------

Signed-off-by: Held, Jarad <jaradheld@gmail.com>
(cherry picked from commit 6bf8617)
Signed-off-by: bitliu <bitliu@tencent.com>

* Bumps Compatibility Matrix for v0.3 (#1002)

Signed-off-by: danehans <daneyonhansen@gmail.com>
(cherry picked from commit d7a2e19)
Signed-off-by: bitliu <bitliu@tencent.com>

* update gateway api support doc (#1022)

* add note about not supported `filters` for `HTTPBackendRef`
* rm `extensionRef` support for `GRPCRoute`
* move the link under docs/latest

Signed-off-by: Arko Dasgupta <arko@tetrate.io>
(cherry picked from commit 9991359)
Signed-off-by: bitliu <bitliu@tencent.com>

* release(v0.3.0): add release notes and release announcement (#1013)

* release(v0.3.0): add release notes and release announcement

Signed-off-by: bitliu <bitliu@tencent.com>

* update

Signed-off-by: bitliu <bitliu@tencent.com>

---------

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit e55c15f)
Signed-off-by: bitliu <bitliu@tencent.com>

* release: cut v0.3.0 versioned docs (#1025)

Signed-off-by: bitliu <bitliu@tencent.com>
(cherry picked from commit 5b316b4)
Signed-off-by: bitliu <bitliu@tencent.com>

---------

Signed-off-by: bitliu <bitliu@tencent.com>
Signed-off-by: hejianpeng <hejianpeng2@huawei.com>
Signed-off-by: Arko Dasgupta <arko@tetrate.io>
Signed-off-by: dependabot[bot] <support@github.com>
Signed-off-by: danehans <daneyonhansen@gmail.com>
Signed-off-by: AliceProxy <alicewasko@datawire.io>
Signed-off-by: Held, Jarad <jaradheld@gmail.com>
Co-authored-by: zirain <hejianpeng2@huawei.com>
Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Daneyon Hansen <daneyonhansen@gmail.com>
Co-authored-by: Alice Wasko <alicewasko@datawire.io>
Co-authored-by: Jarad <76065018+jcheld@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@zirain zirain zirain approved these changes

@arkodg arkodg arkodg left review comments

@Xunzhuo Xunzhuo Xunzhuo left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

0.3.0

Development

Successfully merging this pull request may close these issues.

HTML generated docs for Gateway API Extensions

5 participants

@danehans @codecov-commenter @zirain @arkodg @Xunzhuo