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

Jump to bottom

Auto-generate docs for NGF CRDs #1754

Open
Tracked by #1758
pleshakov opened this issue Mar 21, 2024 · 2 comments · May be fixed by #1884
Open
Tracked by #1758

Auto-generate docs for NGF CRDs #1754

pleshakov opened this issue Mar 21, 2024 · 2 comments · May be fixed by #1884
Assignees
@lucacome
Labels
documentation Improvements or additions to documentation enhancement New feature or request refined Requirements are refined and the issue is ready to be implemented. size/medium Estimated to be completed within a week
Milestone
v1.3.0

Comments

@pleshakov
Copy link
Contributor

Currently, NGF has only one CRD.
The doc for it is here https://github.com/nginxinc/nginx-gateway-fabric/blob/8612c42d8badb8e13b1baf675821350e27395c23/site/content/how-to/configuration/control-plane-configuration.md , visualized https://docs.nginx.com/nginx-gateway-fabric/how-to/configuration/control-plane-configuration/

Note how that doc describes each field of the resource.

As we add more CRDs, it will become tedious to write and maintain docs for fields. Especially considering that the source of truth (the fields + documentation for them) for documentation is go code https://github.com/nginxinc/nginx-gateway-fabric/blob/8612c42d8badb8e13b1baf675821350e27395c23/apis/v1alpha1/nginxgateway_types.go , so we will need to keep the docs in sync with the go files.

Find a way to generate docs for CRDs based on the source code.

Notes:
Example of auto-generated docs in the Gateway API -- https://gateway-api.sigs.k8s.io/reference/spec/
@pleshakov pleshakov added the enhancement New feature or request label Mar 21, 2024
@kate-osborn
Copy link
Contributor

Gateway API uses: https://github.com/ahmetb/gen-crd-api-reference-docs, but this is no longer maintained. There's another project that does the same thing here: https://github.com/elastic/crd-ref-docs

@kate-osborn
Copy link
Contributor

@mpstefan I think we should add this to the 1.3 milestone because we will add a few new CRDs that need documentation.

@mpstefan mpstefan mentioned this issue Apr 1, 2024
Open
@mpstefan mpstefan added this to the v1.3.0 milestone Apr 1, 2024
@mpstefan mpstefan added release-engineering Relates to all release engineering tasks documentation Improvements or additions to documentation refined Requirements are refined and the issue is ready to be implemented. size/medium Estimated to be completed within a week and removed release-engineering Relates to all release engineering tasks labels Apr 1, 2024
@lucacome lucacome assigned lucacome and unassigned lucacome Apr 4, 2024
@lucacome lucacome self-assigned this Apr 25, 2024
@lucacome lucacome linked a pull request Apr 25, 2024 that will close this issue
Open
6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@lucacome lucacome

Labels
documentation Improvements or additions to documentation enhancement New feature or request refined Requirements are refined and the issue is ready to be implemented. size/medium Estimated to be completed within a week
Projects
NGINX Gateway Fabric
Status: 👀 In Review
Milestone
v1.3.0
Development

Successfully merging a pull request may close this issue.

Generate API docs lucacome/nginx-kubernetes-gateway
4 participants
@lucacome @pleshakov @mpstefan @kate-osborn