diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 9da958b1e..55c2c4b3c 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -15,7 +15,6 @@ config: ignores: - "**/CHANGELOG.md" - - "docs/specification" - "node_modules" - "tmp" - "**/protos.md" # auto-generated diff --git a/docs/architecture.md b/docs/architecture.md index c6f3a78de..2a7df0c22 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -42,4 +42,4 @@ erDiagram ``` - \ No newline at end of file + \ No newline at end of file diff --git a/docs/concepts/syncs.md b/docs/concepts/syncs.md index 5ef3b0993..10f1c8d18 100644 --- a/docs/concepts/syncs.md +++ b/docs/concepts/syncs.md @@ -42,7 +42,7 @@ This stream connection is defined by the [sync service protobuf definition](http flagd start --uri grpc://grpc-sync-source ``` -In this example, `grpc-sync-source` is a grpc target implementing [sync.proto](../reference/flag-sync-protocol.md) definition. +In this example, `grpc-sync-source` is a grpc target implementing [sync.proto](../reference/specifications/protos.md#syncv1sync_serviceproto) definition. See [sync source](../reference/sync-configuration.md#source-configuration) configuration for details. --- diff --git a/docs/reference/custom-operations/fractional-operation.md b/docs/reference/custom-operations/fractional-operation.md index f148a4e3e..286c8884c 100644 --- a/docs/reference/custom-operations/fractional-operation.md +++ b/docs/reference/custom-operations/fractional-operation.md @@ -25,7 +25,7 @@ OpenFeature allows clients to pass contextual information which can then be used ``` See the [headerColor](https://github.com/open-feature/flagd/blob/main/samples/example_flags.flagd.json#L88-#L133) flag. -The `defaultVariant` is `red`, but it contains a [targeting rule](reusable_targeting_rules.md), meaning a fractional evaluation occurs for flag evaluation with a `context` object containing `email` and where that `email` value contains `@faas.com`. +The `defaultVariant` is `red`, but it contains a [targeting rule](../flag-definitions.md#targeting-rules), meaning a fractional evaluation occurs for flag evaluation with a `context` object containing `email` and where that `email` value contains `@faas.com`. In this case, `25%` of the evaluations will receive `red`, `25%` will receive `blue`, and so on. diff --git a/docs/reference/flag-definitions.md b/docs/reference/flag-definitions.md index 324770066..ce03c724b 100644 --- a/docs/reference/flag-definitions.md +++ b/docs/reference/flag-definitions.md @@ -145,7 +145,7 @@ A targeting rule **must** be valid JSON. Flagd uses a modified version of [JSON Logic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules. The output of the targeting rule **must** match the name of one of the variants defined above. If an invalid or null value is returned by the targeting rule, the `defaultVariant` value is used. -If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the flag values to be cached, this behavior is described [here](../other_resources/caching.md). +If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the flag values to be cached, this behavior is described [here](specifications/rpc-providers.md#caching). #### Evaluation Context diff --git a/docs/reference/flagd-cli/flagd.md b/docs/reference/flagd-cli/flagd.md index 305d21f2d..d96802416 100644 --- a/docs/reference/flagd-cli/flagd.md +++ b/docs/reference/flagd-cli/flagd.md @@ -1,4 +1,5 @@ + ## 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. @@ -13,6 +14,6 @@ Flagd is a simple command line tool for fetching and presenting feature flags to ### SEE ALSO -* [flagd start](flagd_start) - Start flagd -* [flagd version](flagd_version) - Print the version number of flagd +* [flagd start](flagd_start.md) - Start flagd +* [flagd version](flagd_version.md) - Print the version number of flagd diff --git a/docs/reference/flagd-cli/flagd/flagd.md b/docs/reference/flagd-cli/flagd/flagd.md deleted file mode 100644 index 97c4ae6a6..000000000 --- a/docs/reference/flagd-cli/flagd/flagd.md +++ /dev/null @@ -1,18 +0,0 @@ - -## 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) - Start flagd -* [flagd version](flagd_version) - Print the version number of FlagD - diff --git a/docs/reference/flagd-cli/flagd/flagd_start.md b/docs/reference/flagd-cli/flagd/flagd_start.md deleted file mode 100644 index a633b66ad..000000000 --- a/docs/reference/flagd-cli/flagd/flagd_start.md +++ /dev/null @@ -1,41 +0,0 @@ - -## flagd start - -Start flagd - -``` -flagd start [flags] -``` - -### Options - -``` - -b, --bearer-token string DEPRECATED: Superseded by --sources. - -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 - -z, --log-format string Set the logging format, e.g. console or json (default "console") - -t, --metrics-exporter string Set the metrics exporter. Default(if unset) is Prometheus. Can be override to otel - OpenTelemetry metric exporter. Overriding to otel require otelCollectorURI to be present - -m, --metrics-port int32 Port to serve metrics on (default 8014) - -o, --otel-collector-uri string Set the grpc URI of the OpenTelemetry collector for flagd runtime. If unset, the collector setup will be ignored and traces will not be exported. - -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. - -s, --sources string JSON representation of an array of SourceConfig objects. This object contains 2 required fields, uri (string) and provider (string). Documentation for this object: https://github.com/open-feature/flagd/blob/main/docs/configuration/configuration.md#sync-provider-customisation - -y, --sync-provider string DEPRECATED: Set a sync provider e.g. filepath or remote - -a, --sync-provider-args stringToString DEPRECATED: 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 (http and grpc) or FeatureFlagConfiguration. When flag keys are duplicated across multiple providers the merge priority follows the index of the flag arguments, as such flags from the uri at index 0 take the lowest precedence, with duplicated keys being overwritten by those from the uri at index 1. 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) - 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/reference/flagd-cli/flagd/flagd_version.md b/docs/reference/flagd-cli/flagd/flagd_version.md deleted file mode 100644 index 305ecafb2..000000000 --- a/docs/reference/flagd-cli/flagd/flagd_version.md +++ /dev/null @@ -1,26 +0,0 @@ - -## 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) - 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/reference/flagd-cli/flagd_start.md b/docs/reference/flagd-cli/flagd_start.md index a633b66ad..4359c29bf 100644 --- a/docs/reference/flagd-cli/flagd_start.md +++ b/docs/reference/flagd-cli/flagd_start.md @@ -1,4 +1,5 @@ + ## flagd start Start flagd @@ -37,5 +38,5 @@ flagd start [flags] ### SEE ALSO -* [flagd](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. +* [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/reference/flagd-cli/flagd_version.md b/docs/reference/flagd-cli/flagd_version.md index e8b23087d..d14235dea 100644 --- a/docs/reference/flagd-cli/flagd_version.md +++ b/docs/reference/flagd-cli/flagd_version.md @@ -1,4 +1,5 @@ + ## flagd version Print the version number of flagd @@ -22,5 +23,5 @@ flagd version [flags] ### SEE ALSO -* [flagd](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. +* [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/reference/specifications/custom-operations/fractional-operation-spec.md b/docs/reference/specifications/custom-operations/fractional-operation-spec.md index 619040818..8e6eb5340 100644 --- a/docs/reference/specifications/custom-operations/fractional-operation-spec.md +++ b/docs/reference/specifications/custom-operations/fractional-operation-spec.md @@ -13,7 +13,7 @@ hash function should be used. This is to ensure that flag resolution requests yi regardless of which implementation of the in-process flagd provider is being used. The supplied array must contain at least two items, with the first item being an optional [json logic variable declaration](https://jsonlogic.com/operations.html#var) -specifying the bucketing property to base the distribution of values on. If not supplied, a concatination of the +specifying the bucketing property to base the distribution of values on. If not supplied, a concatenation of the `flagKey` and `targetingKey` are used: `{"cat": [{"var":"$flagd.flagKey"}, {"var":"targetingKey"}]}`. The remaining items are `arrays`, each with two values, with the first being `string` item representing the name of the variant, and the second being a `float` item representing the percentage for that variant. The percentages of all items must add up to diff --git a/docs/reference/specifications/rpc-providers.md b/docs/reference/specifications/rpc-providers.md index 599a5ecda..a5f6c8b9f 100644 --- a/docs/reference/specifications/rpc-providers.md +++ b/docs/reference/specifications/rpc-providers.md @@ -8,13 +8,13 @@ as it is done in the [OpenFeature Operator](https://github.com/open-feature/open Prerequisites: - Understanding of [general provider concepts](https://openfeature.dev/docs/reference/concepts/provider/) -- Proficiency in the chosen programming language (check the language isn't already covered by the [existing providers](../usage/flagd_providers.md)) +- Proficiency in the chosen programming language (check the language isn't already covered by the [existing providers](../providers.md)) ## flagd Evaluation API Fundamentally, RPC providers use the [evaluation schema](./protos.md#schemav1schemaproto) to connect to flagd, initiate evaluation RPCs, and listen for changes in the flag definitions. In order to do this, you must generate the gRPC primitives (message types and client) using the protobuf code generation mechanisms available in your language. -If you are unable to use gRPC code generation, you can also use REST (via the [connect protocol](https://buf.build/blog/connect-a-better-grpc)) to communivate with flagd, though in this case, you will not be able to open a stream to listen for changes. +If you are unable to use gRPC code generation, you can also use REST (via the [connect protocol](https://buf.build/blog/connect-a-better-grpc)) to communicate with flagd, though in this case, you will not be able to open a stream to listen for changes. ### Protobuf @@ -39,7 +39,7 @@ cd schemas/protobuf buf generate --template buf.gen.{chosen language}.yaml ``` -As an alternative to buf, use the .proto file directly along with whatever protoc-related tools or plugins avaialble for your language. +As an alternative to buf, use the .proto file directly along with whatever protoc-related tools or plugins available for your language. Move the generated code (following convention for the chosen language) and add its location to .gitignore @@ -56,7 +56,7 @@ In-process flagd providers should do the following to make use of OpenFeature v0 - note that the SDK will automatically emit `PROVIDER_READY`/`PROVIDER_ERROR` according to the termination of the `initialization` function - throw an exception or terminate abnormally if a connection cannot be established during `initialization` - For gRPC based sources (i.e. flagd-proxy), attempt to restore the streaming connection to flagd-proxy (if the connection cannot be established or is broken): - - If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responsees are based on potentially outdated Flag definition. + - If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responses are based on potentially outdated Flag definition. - reconnection should be attempted with an exponential back-off, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration)) - reconnection should be attempted up to `maxSyncRetryDelay` times (see [configuration](#configuration)) - `PROVIDER_READY` and `PROVIDER_CONFIGURATION_CHANGED` should be emitted, in that order, after successful reconnection diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index fdb731bfb..6012ad93a 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,7 +5,7 @@ If a flag or targeting rule isn't proceeding the way you'd expect, you may want to enable more verbose logging. flagd and flagd providers typically have debug or verbose logging modes that you can use for this sort of troubleshooting. -You can do this in the standalone version of flagd by starting it with the `--debug` flag (see [CLI](./reference/flagd-cli/flagd/flagd.md) for more information). +You can do this in the standalone version of flagd by starting it with the `--debug` flag (see [CLI](./reference/flagd-cli/flagd.md) for more information). _In-process_ providers which embed the flag evaluation engine use a logging consistent with their implementation language and SDK. See your provider's documentation for details on how to enable verbose logging. diff --git a/flagd/cmd/doc.go b/flagd/cmd/doc.go index 802bdcc2f..4ae317568 100644 --- a/flagd/cmd/doc.go +++ b/flagd/cmd/doc.go @@ -2,7 +2,6 @@ package cmd import ( "fmt" - "strings" "github.com/spf13/cobra/doc" ) @@ -10,12 +9,13 @@ import ( // GenerateDoc generates cobra docs of the cmd func GenerateDoc(path string) error { linkHandler := func(name string) string { - return strings.ReplaceAll(name, ".md", "") + return name } filePrepender := func(filename string) string { - return "\n" + return "\n\n" } + if err := doc.GenMarkdownTreeCustom(rootCmd, path, filePrepender, linkHandler); err != nil { return fmt.Errorf("error generating docs: %w", err) } diff --git a/mkdocs.yml b/mkdocs.yml index 28a1f6478..dcc1032ee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,9 +70,9 @@ nav: - 'Architecture': 'architecture.md' - 'Reference': - 'CLI': - - 'Commands': 'reference/flagd-cli/flagd.md' - - '"start" Command': 'reference/flagd-cli/flagd_start.md' - - '"version" Command': 'reference/flagd-cli/flagd/flagd_version.md' + - 'Overview': 'reference/flagd-cli/flagd.md' + - 'Start': 'reference/flagd-cli/flagd_start.md' + - 'Version': 'reference/flagd-cli/flagd_version.md' - 'Sync Configuration': 'reference/sync-configuration.md' - 'Flag Definitions': - 'Definition Overview': 'reference/flag-definitions.md'