Autogenerate API Reference Documentation #546
Conversation
This commit adds a make target to autogenerate the API Reference HTML for any CRDs in the api/ directory. A future commit will make this automatic when generating CRD manifests (currently this results in a `Last Updated` footer being modified every time this is run, which would make git merges painful)
This removes the troublesome footer so the API reference documentation can be generated automatically without risk of merge conflicts, or forgetting to run the generation of the docs
|
@ChunyiLyu Thanks for the feedback :) I'm not sure I agree that those items should be removed; while they're essentially trimmed down versions of Core API types, we still have a materially different API, and these types that we have defined are our API. The reason they're at the top is that crd-ref-docs sorts the types alphabetically, which I think matches other ref docs. I think we could selectively remove fields if we wish - it should be just a case of changing the .tpl to have an if statement so it only adds the line for a type if it's not a drop list- cluster-operator/docs/api/autogen/templates/gv_details.tpl Lines 15 to 17 in be56b8c We can also add whatever headers, titles, etc. we would like to make this neater. I notice that a lot of the fields are missing either descriptions for fields or for the type itself, which is strange. I'll have to do some more digging later to work out why. |
This contains my fixes to alias types
GitHub Wiki renders asciidoc as HTML natively, so there's no need to messily convert in this repo.
This workflow will trigger on every push to main, and will update the Wiki tab of the repo with the API reference for the operator.
ansd
left a comment
ansd
left a comment
There was a problem hiding this comment.
Awesome :)
When I run make api-reference, I see some warnings:
> make api-reference
go mod download
grep _ tools/tools.go | awk -F '"' '{print $2}' | xargs -t go install
go install github.com/elastic/crd-ref-docs github.com/go-delve/delve/cmd/dlv github.com/onsi/ginkgo/ginkgo github.com/sclevine/yj sigs.k8s.io/controller-tools/cmd/controller-gen sigs.k8s.io/kind sigs.k8s.io/kustomize/kustomize/v3
crd-ref-docs \
--source-path ./api/v1beta1 \
--config ./docs/api/autogen/config.yaml \
--templates-dir ./docs/api/autogen/templates \
--output-path ./docs/api/rabbitmq.com.ref.asciidoc \
--max-depth 30
2021-01-14T11:48:37.922+0100 INFO crd-ref-docs Loading configuration {"path": "./docs/api/autogen/config.yaml"}
2021-01-14T11:48:37.922+0100 INFO crd-ref-docs Processing source directory {"directory": "./api/v1beta1", "depth": 30}
2021-01-14T11:48:38.493+0100 WARN crd-ref-docs Failed to find type {"name": "Quantity", "package": "k8s.io/apimachinery/pkg/api/resource"}
2021-01-14T11:48:38.495+0100 WARN crd-ref-docs Failed to find type {"name": "IntOrString", "package": "k8s.io/apimachinery/pkg/util/intstr"}
2021-01-14T11:48:38.500+0100 INFO crd-ref-docs Rendering output {"path": "./docs/api/rabbitmq.com.ref.asciidoc"}
2021-01-14T11:48:38.504+0100 INFO crd-ref-docs CRD reference documentation generated
2021-01-14T11:48:38.504+0100 INFO crd-ref-docs Execution time: 582.154111msNot sure why it doesn't find Quantity in https://github.com/kubernetes/apimachinery/blob/53a9c91c2218bcb4b5de001c441888cb77b48939/pkg/api/resource/quantity.go#L89.
I think it doesn't deal well with Go types that aren't in the Kubernetes API docs. Quantity isn't a 'K8s API type', so it doesn't find it. I'd like to make a future enhancement to allow it to find arbitrary Go types in https://pkg.go.dev/, allowing that redirection. |
This was achieved by running `go mod tidy`
This closes #528
Note to reviewers: remember to look at the commits in this PR and consider if they can be squashed
Summary Of Changes
This PR allows auto generation of the API Reference documentation from the
api/directory in the repo.Running
make api-reference, or any other make target that requires auto generation of code, will cause the reference docs to be regenerated. They now live atdocs/api/rabbitmq.com.ref.asciidoc. This format can be interpreted by GitHub and rendered as HTML.Allowing this documentation to be autogenerated will prevent API elements/descriptions being updated without the API reference docs being updated alongside.
This PR also includes a GitHub Action to take the generated Asciidoc and insert it into our GitHub Wiki, so that our API reference is neatly packaged together with the source code.
Additional Context
This PR uses elastic/crd-ref-docs to parse the
api/directory for API definitions, and generate anasciidocfile containing the API reference. It then uses a docker image containing asciidoctor/asciidoctor/ to convert the file to HTML.I used the Elastic tool as it is better suited to more modern operators; the frequently suggested ahmetb/gen-crd-api-reference-docs does not easily support go modules, and does not support Kubebuilder v2-generated frameworks.
If you'd like to check what the resultant doc would look like on our Wiki, try it out by going to https://github.com/rabbitmq/cluster-operator/blob/autogen-api-ref/docs/api/rabbitmq.com.ref.asciidoc