-
Notifications
You must be signed in to change notification settings - Fork 79
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.
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
Generate API docs #1884
Generate API docs #1884
Conversation
9838a02
to
06d6744
Compare
@nginxinc/nginx-docs I need your help to make the new page look good 😅 |
@@ -0,0 +1,1151 @@ | |||
--- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there any way to see this page rendered? It doesn't seem to have deployed in Netlify (although I might just be looking in the wrong place 😅)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
seems like it didn't deploy after a force push, we have it now https://deploy-preview-1884--nginx-gateway-fabric.netlify.app/nginx-gateway-fabric/reference/api/
It doesn't look good 😅
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should have an example of generated API documentation for other software: I'll inquire with the team what the caveats are.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The NGINX One API ref guide just calls the JSON spec and redoc does the formatting auto-magically.
Published output: https://docs.nginx.com/nginx-one/reference/api/nginx-one-api-reference/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@travisamartin it's a little bit different from the Open API Spec, we don't have a JSON.
It's something similar to https://gateway-api.sigs.k8s.io/reference/spec/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@ADubhlaoich @travisamartin any chance you can help with this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@lucacome Some more investigation work is required on our end about if an existing template can be adapted for this.
Does the Gateway API follow a specific, known schema?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure, this is just an html page
@Jcahilltorre @travisamartin Any thoughts on the formatting issues for this generated API documentation? I think there's some examples without these formatting issues in NGINX Management Suite, which are OpenAPI based IIRC. |
7383009
to
ed76c4d
Compare
Problem: We want to have our CRDs documented Solution: Use gen-crd-api-reference-docs to automatically generate the docs
dd7cb3a
to
5916cb9
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Docs solutions need to be discussed with the docs team before implementation and must align with the NGINX content standards. Please close this PR until it can be brought into alignment with how we publish API documentation for NGINX and F5 products.
Proposed changes
Problem: We want to have our CRDs documented
Solution: Use gen-crd-api-reference-docs to automatically generate the
docs
Closes #1754
Checklist
Before creating a PR, run through this checklist and mark each as complete.
Release notes
If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.