diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 9987e2816..f21ec2bc1 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -53,6 +53,20 @@ jobs: go-version: ${{ env.GO_VERSION }} - run: make lint + docs-check: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3 + - name: Setup go + uses: actions/setup-go@6edd4406fa81c3da01a34fa6f6343087c207a568 # v3 + with: + go-version: ${{ env.GO_VERSION }} + - run: make generate-docs + - name: Check no diff + run: | + if [ ! -z "$(git status --porcelain)" ]; then echo "Doc generation produced diff. Run 'make generate-docs' and commit results."; exit 1; fi + test: runs-on: ubuntu-latest env: diff --git a/Makefile b/Makefile index f9ebfa7d7..5c9baf7cf 100644 --- a/Makefile +++ b/Makefile @@ -37,3 +37,5 @@ install-mockgen: mockgen: install-mockgen mockgen -source=pkg/sync/http/http_sync.go -destination=pkg/sync/http/mock/http.go -package=syncmock mockgen -source=pkg/eval/ievaluator.go -destination=pkg/eval/mock/ievaluator.go -package=evalmock +generate-docs: + go run ./cmd/doc/main.go diff --git a/cmd/doc.go b/cmd/doc.go new file mode 100644 index 000000000..d261d862c --- /dev/null +++ b/cmd/doc.go @@ -0,0 +1,8 @@ +package cmd + +import "github.com/spf13/cobra/doc" + +// GenerateDoc generates cobra docs of the cmd +func GenerateDoc(path string) error { + return doc.GenMarkdownTree(rootCmd, path) +} diff --git a/cmd/doc/main.go b/cmd/doc/main.go new file mode 100644 index 000000000..e2200f8fd --- /dev/null +++ b/cmd/doc/main.go @@ -0,0 +1,15 @@ +package main + +import ( + "log" + + "github.com/open-feature/flagd/cmd" +) + +const docPath = "./docs/configuration" + +func main() { + if err := cmd.GenerateDoc(docPath); err != nil { + log.Fatal(err) + } +} diff --git a/cmd/root.go b/cmd/root.go index 3d8fe26ce..831f2b457 100644 --- a/cmd/root.go +++ b/cmd/root.go @@ -21,7 +21,8 @@ var rootCmd = &cobra.Command{ Use: "flagd", Short: "Flagd is a simple command line tool for fetching and presenting feature flags to services. " + "It is designed to conform to Open Feature schema for flag definitions.", - Long: ``, + Long: ``, + DisableAutoGenTag: true, // Uncomment the following line if your bare application // has an action associated with it: // Run: func(cmd *cobra.Command, args []string) { }, @@ -30,8 +31,6 @@ var rootCmd = &cobra.Command{ // Execute adds all child commands to the root command and sets flags appropriately. // This is called by main.main(). It only needs to happen once to the rootCmd. func Execute(version string, commit string, date string) { - rootCmd.AddCommand(startCmd) - rootCmd.AddCommand(versionCmd) Version = version Commit = commit Date = date @@ -49,6 +48,8 @@ func init() { // will be global for your application. rootCmd.PersistentFlags().BoolVarP(&Debug, "debug", "x", false, "verbose logging") rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.agent.yaml)") + rootCmd.AddCommand(startCmd) + rootCmd.AddCommand(versionCmd) } // initConfig reads in config file and ENV variables if set. diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 992aae07f..e45dc5fcf 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -3,22 +3,7 @@ `flagd` supports configuration via config file, environment variables and flags. In cases of conflict, flags have the highest priority, followed by environment variables and finally config file. -Supported flags are as follows (result of running `./flagd start --help`): - -``` - -b, --bearer-token string Set a bearer token to use for remote sync - -C, --cors-origin strings CORS allowed origins, * will allow all origins - -h, --help help for start - -m, --metrics-port int32 Port to serve metrics on (default 8014) - -p, --port int32 Port to listen on (default 8013) - -c, --server-cert-path string Server side tls certificate path - -k, --server-key-path string Server side tls key path - -d, --socket-path string Flagd socket path. With grpc the service will become available on this address. With http(s) the grpc-gateway proxy will use this address internally. - -a, --sync-provider-args stringToString Sync provider arguments as key values separated by = (default []) - -f, --uri .yaml/.yml/.json Set a sync provider uri to read data from, this can be a filepath,url or FeatureFlagConfiguration. Using multiple providers is supported however if flag keys are duplicated across multiple sources it may lead to unexpected behavior. Please note that if you are using filepath, flagd only supports files with .yaml/.yml/.json extension. - -e, --evaluator string DEPRECATED: Set an evaluator e.g. json, yaml/yml. Please note that yaml/yml and json evaluations work the same (yaml/yml files are converted to json internally) (default "json") - -y, --sync-provider string DEPRECATED: Set a sync provider e.g. filepath or remote -``` +Supported flags are documented (auto-generated) [here](./flagd_start.md). Environment variable keys are uppercased, prefixed with `FLAGD_` and all `-` are replaced with `_`. For example, `sync-provider-args` in environment variable form is `FLAGD_SYNC_PROVIDER_ARGS`. diff --git a/docs/configuration/flagd.md b/docs/configuration/flagd.md new file mode 100644 index 000000000..90cd032fd --- /dev/null +++ b/docs/configuration/flagd.md @@ -0,0 +1,17 @@ +## flagd + +Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions. + +### Options + +``` + --config string config file (default is $HOME/.agent.yaml) + -x, --debug verbose logging + -h, --help help for flagd +``` + +### SEE ALSO + +* [flagd start](flagd_start.md) - Start flagd +* [flagd version](flagd_version.md) - Print the version number of FlagD + diff --git a/docs/configuration/flagd_start.md b/docs/configuration/flagd_start.md new file mode 100644 index 000000000..145ac9cbe --- /dev/null +++ b/docs/configuration/flagd_start.md @@ -0,0 +1,36 @@ +## flagd start + +Start flagd + +``` +flagd start [flags] +``` + +### Options + +``` + -b, --bearer-token string Set a bearer token to use for remote sync + -C, --cors-origin strings CORS allowed origins, * will allow all origins + -e, --evaluator string DEPRECATED: Set an evaluator e.g. json, yaml/yml.Please note that yaml/yml and json evaluations work the same (yaml/yml files are converted to json internally) (default "json") + -h, --help help for start + -m, --metrics-port int32 Port to serve metrics on (default 8014) + -p, --port int32 Port to listen on (default 8013) + -c, --server-cert-path string Server side tls certificate path + -k, --server-key-path string Server side tls key path + -d, --socket-path string Flagd socket path. With grpc the service will become available on this address. With http(s) the grpc-gateway proxy will use this address internally. + -y, --sync-provider string DEPRECATED: Set a sync provider e.g. filepath or remote + -a, --sync-provider-args stringToString Sync provider arguments as key values separated by = (default []) + -f, --uri .yaml/.yml/.json Set a sync provider uri to read data from, this can be a filepath,url or FeatureFlagConfiguration. Using multiple providers is supported however if flag keys are duplicated across multiple sources it may lead to unexpected behavior. Please note that if you are using filepath, flagd only supports files with .yaml/.yml/.json extension. +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.agent.yaml) + -x, --debug verbose logging +``` + +### SEE ALSO + +* [flagd](flagd.md) - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions. + diff --git a/docs/configuration/flagd_version.md b/docs/configuration/flagd_version.md new file mode 100644 index 000000000..df2d55bd5 --- /dev/null +++ b/docs/configuration/flagd_version.md @@ -0,0 +1,25 @@ +## flagd version + +Print the version number of FlagD + +``` +flagd version [flags] +``` + +### Options + +``` + -h, --help help for version +``` + +### Options inherited from parent commands + +``` + --config string config file (default is $HOME/.agent.yaml) + -x, --debug verbose logging +``` + +### SEE ALSO + +* [flagd](flagd.md) - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions. + diff --git a/go.mod b/go.mod index 39e5d7eab..0e1456bfd 100644 --- a/go.mod +++ b/go.mod @@ -39,6 +39,7 @@ require ( github.com/beorn7/perks v1.0.1 // indirect github.com/cespare/xxhash/v2 v2.1.2 // indirect github.com/common-nighthawk/go-figure v0.0.0-20200609044655-c4b36f998cf2 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/emicklei/go-restful/v3 v3.9.0 // indirect github.com/evanphx/json-patch/v5 v5.6.0 // indirect @@ -75,6 +76,7 @@ require ( github.com/prometheus/client_model v0.3.0 // indirect github.com/prometheus/common v0.37.0 // indirect github.com/prometheus/procfs v0.8.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/spf13/afero v1.9.3 // indirect github.com/spf13/cast v1.5.0 // indirect github.com/spf13/jwalterweatherman v1.1.0 // indirect diff --git a/go.sum b/go.sum index 3b9bc9cff..dce8e6896 100644 --- a/go.sum +++ b/go.sum @@ -76,6 +76,7 @@ github.com/cncf/xds/go v0.0.0-20210922020428-25de7278fc84/go.mod h1:eXthEFrGJvWH github.com/cncf/xds/go v0.0.0-20211011173535-cb28da3451f1/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs= github.com/common-nighthawk/go-figure v0.0.0-20200609044655-c4b36f998cf2 h1:tjT4Jp4gxECvsJcYpAMtW2I3YqzBTPuB67OejxXs86s= github.com/common-nighthawk/go-figure v0.0.0-20200609044655-c4b36f998cf2/go.mod h1:mk5IQ+Y0ZeO87b858TlA645sVcEcbiX6YqP98kt+7+w= +github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w= github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= @@ -326,6 +327,7 @@ github.com/rs/cors v1.8.3 h1:O+qNyWn7Z+F9M0ILBHgMVPuB1xTOucVd5gtaYyXBpRo= github.com/rs/cors v1.8.3/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU= github.com/rs/xid v1.4.0 h1:qd7wPTDkN6KQx2VmMBLrpHkiyQwgFXRnkOLacUiaSNY= github.com/rs/xid v1.4.0/go.mod h1:trrq9SKmegXys3aeAKXMUTdJsYXVwGY3RLcfgqegfbg= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo= github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=