shifu
shifu copied to clipboard
[doc] add struct tag description to generate documentation automatically
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/.
The struct tag may introduce performance issue. I will check if a better method exists.
currently PR in review at https://github.com/Edgenesis/shifu.run/pull/168
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...
Will close this issue for now and use https://github.com/Edgenesis/shifu/issues/302