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 :

1. Cloned git repo : https://github.com/ahmetb/gen-crd-api-reference-docs/
2. Created an executable binary by running go build command
3. Copied template folder from this repto to Kanister repo
4. 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
5. Added above created binary to template folder.
6. Modified docs target in makefile

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

[Kartik-Garg]

When the command make docs is ran:
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

A snippet of API.md :

[PrasadG193]

@Kartik-Garg let's not commit gen-crd-api-reference-docs binary to the repo.
We can add this binary to the build container that we use to build project. You can find the dockerfile here - https://github.com/kanisterio/kanister/blob/master/docker/build/Dockerfile

[PrasadG193]

We use different image for docs build - https://github.com/kanisterio/kanister/tree/master/docker/docs-build. Sorry for the confusion. We should add the binary in this build image

[PrasadG193]

First we need to decide when do we want to run this comment. And if this needs to be included in the public facing docs. Depending on that we can decide on the right docker image to add this binary.

[Kartik-Garg]

We use different image for docs build - https://github.com/kanisterio/kanister/tree/master/docker/docs-build. Sorry for the confusion. We should add the binary in this build image

Since the crd_documentation tool does not have the latest release, we can not add it to the docs-build, because we will also have to run go build which will require additional packages to be installed, we already have a docker file which contains the go packages (the one which was referred earlier in the comment section).
I have added the additional command in the build docker file

[Kartik-Garg]

First we need to decide when do we want to run this comment. And if this needs to be included in the public facing docs. Depending on that we can decide on the right docker image to add this binary.

makes sense, so I have created a new target called crd_docs , so when make crd_docs is run the API.md is created then.

[Kartik-Garg]

@PrasadG193
I have added the additional changes:

1. Removed the executable binary from template folder, instead downloading the tar.gz asset and building binary in the docker file itself (https://github.com/Kartik-Garg/kanister/blob/1a55c417be803518c50c2df03cb96beb2dad1616/docker/build/Dockerfile#L26)
2. Added new target in the makefile which can be run explicitly whenever we want to create API.md file which contains documentation for API_CRD files : https://github.com/Kartik-Garg/kanister/blob/1a55c417be803518c50c2df03cb96beb2dad1616/Makefile#L211

Test Plan (manual testing) :

1. first I created a custom image locally which has similar code to build dockerfile : https://github.com/kanisterio/kanister/blob/master/docker/build/Dockerfile , in addition added code to create executable binary file which looks something like :
   

2. after pushing this image as: kartikgarg/crd:0.1 , created a new image variable in makefile :
   

3. Added the new target and command to run and test with the docker image:
   

4. Result is successful :
   

5. And API.md file is created:
   

[PrasadG193]

Thanks a lot @Kartik-Garg for adding the Makefile target to build the docs.
We should move these docs to some directory. @pavannd1 @viveksinghggits I think the internal docs like API and Design docs should be in separate /docs folder and the website docs can be moved to /website dir.

[PrasadG193]

@pavannd1 does it make sense to add API docs section in docs.kanister.io and move this doc there? Something like - https://argocd-operator.readthedocs.io/en/latest/reference/api.html/

[viveksinghggits]

@Kartik-Garg
just to confirm this the documentation that is generated will be updated after every release right? Because we would be running make docs after every release.
Once new documentation is generated how would that we checked into the repo again, or thats not requried? Can you explain the workflow please?

[Kartik-Garg]

@Kartik-Garg just to confirm this the documentation that is generated will be updated after every release right? Because we would be running make docs after every release. Once new documentation is generated how would that we checked into the repo again, or thats not requried? Can you explain the workflow please?

@viveksinghggits The documentation would be generated every time we run the make crd_docs command. It would just create the documentation as API.md file. Once, the documentation is created and we need to update the existing one, we can just commit it and push it to repo, since the command creates documentation locally

[viveksinghggits]

@Kartik-Garg
does that mean every time someone changes an API definition they will have to run this command and commit and push the documentation as well?

[Kartik-Garg]

does that mean every time someone changes an API definition they will have to run this command and commit and push the documentation as well?

Yes

[viveksinghggits]

does that mean every time someone changes an API definition they will have to run this command and commit and push the documentation as well?

Yes

Let's add this workflow here so that people are aware https://github.com/kanisterio/kanister/blob/master/CONTRIBUTING.md#contributing-code

[viveksinghggits]

Just another sub heading maybe, stating what to do when you update api types. I am assuming it's just the api types that we are concerned about here, right?

[viveksinghggits]

I would rather prefer adding a subheading under to https://github.com/kanisterio/kanister/blob/master/CONTRIBUTING.md#contributing-code.

### Updating the API types

If your changes involve the Kanister API types as well, make sure you generate the API documentation using below command and then push the updated `API.md` as well.

Update wording and grammar please 😄 .

[Kartik-Garg]

I would rather prefer adding a subheading under to https://github.com/kanisterio/kanister/blob/master/CONTRIBUTING.md#contributing-code.

### Updating the API types

If your changes involve the Kanister API types as well, make sure you generate the API documentation using below command and then push the updated `API.md` as well.

Update wording and grammar please smile .

Thanks a lot! @viveksinghggits
I have made changes accordingly, please do let me know if everything seems alright

[viveksinghggits]

Looks good. Thanks @Kartik-Garg 🚀