Auto-generate CRD Documentation #1342

[Kartik-Garg]

Change Overview

Created CRD documentation using https://github.com/ahmetb/gen-crd-api-reference-docs/ , in response to the issue #1342 , added template folder, which contains files, which are used by the auto CRD generator tool, to create the CRD documentation, the documentation is named as "API.md" .

Signed-off-by: Kartik-Garg [email protected]

Plan of action :

• cloned git repo : https://github.com/ahmetb/gen-crd-api-reference-docs/
• created an executable binary by running go build command
• copied template folder from this repto to Kanister repo
• ran the following command:
  /path/to/gen-crd-api-reference-docs \ -config "/path/to/example-config.json" \ -api-dir "github.com/knative/build/pkg/apis/build/v1alpha1" \ -out-file docs.html

Pull request type

Please check the type of change your PR introduces:

• 🚧 Work in Progress
• 🌈 Refactoring (no functional changes, no api changes)
• 🐹 Trivial/Minor
• 🐛 Bugfix
• 🌻 Feature
• 🗺️ Documentation
• 🤖 Test

Issues

• fixes Auto-generate CRD Documentation #1342

Test Plan

• 💪 Manual
• ⚡ Unit test
• 💚 E2E

[PrasadG193]

I see descriptions on a lot of fields are missing. We need to add missing comments on the struct fields. This can be handled separately. I will file an issue for that #1721

[Kartik-Garg]

@PrasadG193 I have made changes to the Makefile as well, so now when the command make docs is ran, the API CRD documentation is also generated automatically with the name as "API.md" , one question I had was about the structure of the project, which is:
Since, we are using : https://github.com/ahmetb/gen-crd-api-reference-docs/ to auto-generate CRD documentation, I wanted to know where do I store the exec binary file and other documents related to creation of documents, as of now I have stored all of them in a folder called template (template folder which contain files with .tpl extension, need to exist in order for the library to create the documentation)

[Kartik-Garg]

I see descriptions on a lot of fields are missing. We need to add missing comments on the struct fields. This can be handled separately. I will file an issue for that #1721

I have made final changes in the makefile now, so even if any changes/modifications are made(comments on struct fields), when the command make docs is ran, the API CRD documentation named "API.md" is created.
A snippet of the document created :

Output of the make docs command would look something like :
running DOCS_CMD in the containerized build environment Removing everything under '_build'... Scanning... Validating... The HTML pages are in _build/html. /usr/local/lib/python3.6/site-packages/sphinx_rtd_theme/search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead. {{ super() }} make[1]: Entering directory '/home/kartik/Documents/OpenSource/Kanister/kanister' running CMD in the containerized build environment I1108 08:43:15.790940 1 main.go:132] parsing go packages in directory ./pkg/apis/cr/v1alpha1 I1108 08:43:33.314445 1 main.go:234] using package=github.com/kanisterio/kanister/pkg/apis/cr/v1alpha1 W1108 08:43:33.319322 1 main.go:445] not found external link source for type interface{} W1108 08:43:33.320886 1 main.go:445] not found external link source for type interface{} I1108 08:43:33.322448 1 main.go:170] written to API.md