[doc] add struct tag description to generate documentation automatically

[Yang-Xijie]

Now this project uses godoc to generate documentation for developers. However, we also need to generate documentation for users.

Now API references for users are hosted on https://shifu.run/docs/references/api/. One disadvantage of this is that we should manually generate these API references, which is a time-wasting.

We can use the struct tag feature in Golang to make the reference information in source codes. Just as the following example:

package main

import (
	"fmt"
	"github.com/fatih/structs"
)

type User struct {
	id   int    `description-en:"user's ID" description-zh:"用户的ID"`
	name string `description-en:"user's name" description-zh:"用户的名字"`
	age  int    `description-en:"user's age" description-zh:"用户的年龄"`
	date `description-en:"account's date" description-zh:"用户相关的日期"`
}

type date struct {
	createdAt string `description-en:"created time of account" description-zh:"账户创建的日期"`
	updatedAt string `description-en:"updated time of account" description-zh:"账户更新的时间"`
}

func main() {
	user := &User{}
	fields := structs.Fields(user)
	getInfoOf(fields, "")
	// id: [user's ID, 用户的ID]
	// name: [user's name, 用户的名字]
	// age: [user's age, 用户的年龄]
	// date: [account's date, 用户相关的日期]
	//     createdAt: [created time of account, 账户创建的日期]
	//     updatedAt: [updated time of account, 账户更新的时间]
}

func getInfoOf(fields []*structs.Field, prefix string) {
	for _, field := range fields {
		tag_name := field.Name()
		tag_en := field.Tag("description-en")
		tag_zh := field.Tag("description-zh")
		if field.IsEmbedded() {
			fmt.Printf("%s: [%s, %s]\n", tag_name, tag_en, tag_zh)
			prefix_new := fmt.Sprintf("    %s", prefix)
			getInfoOf(field.Fields(), prefix_new)
		} else {
			fmt.Printf("%s%s: [%s, %s]\n", prefix, tag_name, tag_en, tag_zh)
		}
	}
}

In this project, for example, the API reference of DeviceShifuDriverProperties is in https://shifu.run/docs/references/api/deviceshifu-configmap#deviceshifudriverproperties. We can add struct tag in go codes (pkg/deviceshifu/deviceshifubase_config.go) as follows:

// DeviceShifuDriverProperties properties of deviceshifuDriver
type DeviceShifuDriverProperties struct {
	DriverSku       string `yaml:"driverSku" usage-en:"hardware models supported by the driver, such as Hikvision Camera." usage-zh:"表示驱动所适用的硬件型号，如 Hikvision Camera。"`
	DriverImage     string `yaml:"driverImage" usage-en:"(string) container image name of the driver, such as driver/hikvision-camera:v1.2.3." usage-zh:"表示驱动的容器镜像名称，如 driver/hikvision-camera:v1.2.3。"`
	DriverExecution string `yaml:"driverExecution,omitempty" usage-en:"execution path of the drive. For command line driver, relative/absolute path of the driver execution file needs to be filled in, such as python driver.py or C:\\driver.exe." uages-zh:"表示驱动的执行路径。针对于命令行的驱动，这里需要填写驱动的执行文件的相对/绝对路径，如 python driver.py 或 C:\\driver.exe。"`
}

Then we can use a script to generate according markdown strings to put on https://shifu.run/docs/references/api/.

[Yang-Xijie]

The struct tag may introduce performance issue. I will check if a better method exists.

[tomqin93]

currently PR in review at https://github.com/Edgenesis/shifu.run/pull/168

[Yang-Xijie]

I found that k8s use auto-generated method to host their docs: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/replica-set-v1/#auto-generated-edit-notice

It will be great if we apply this method...

[tomqin93]

Will close this issue for now and use https://github.com/Edgenesis/shifu/issues/302