chore: docs rework

Signed-off-by: Todd Baert <[email protected]>

.github/workflows/build.yaml

@@ -28,7 +28,7 @@ jobs:
       GOBIN: /home/runner/work/open-feature/flagd/bin
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
       - name: Setup go
         uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4
         with:
@@ -40,7 +40,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
       - name: Setup go
         uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4
         with:
@@ -58,7 +58,7 @@ jobs:
       GOBIN: /home/runner/work/open-feature/flagd/bin
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
       - name: Setup go
         uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4
         with:
@@ -73,7 +73,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
         with:
           submodules: recursive
 
@@ -118,7 +118,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
         with:
           submodules: recursive
 

.github/workflows/dev-benches-page.yml

@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
         with:
           ref: gh-pages
       - name: Setup Pages

.github/workflows/markdown-checks.yaml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Check out code
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
 
       - name: Lint Markdown files
         run: make markdownlint

.github/workflows/publish-benchmark.yaml

@@ -14,7 +14,7 @@ jobs:
     if: github.repository == 'open-feature/flagd'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+      - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
 
       - name: Setup go
         uses: actions/setup-go@93397bea11091df50f3d7e59dc26a7711a8bcfbe # v4

.github/workflows/release-please.yaml

@@ -75,7 +75,7 @@ jobs:
       VERSION: v${{ needs.release-please.outputs[format('{0}_version', matrix.path)] }}
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
         with:
           ref: ${{ env.TAG }}
 
@@ -119,7 +119,7 @@ jobs:
             COMMIT=${{ github.sha }}
             DATE=${{ needs.release-please.outputs.date }}
       - name: Install Cosign
-        uses: sigstore/cosign-installer@ef6a6b364bbad08abd36a5f8af60b595d12702f8
+        uses: sigstore/cosign-installer@9c520b997e685cb69e1ac226f7dce8114e8f36df
 
       - name: Sign the image
         run: |
@@ -166,7 +166,7 @@ jobs:
       BUILD_ARGS: '-a -ldflags "-X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}"'
     steps:
       - name: Checkout
-        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4
         with:
           ref: ${{ env.TAG }}
       - name: Set up Go

.gitignore

@@ -14,4 +14,5 @@ go.work.sum
 bin/
 
 # built documentation
-site
+site
+.cache/

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "spec"]
 	path = spec
 	url = https://github.com/open-feature/spec.git
+[submodule "schemas"]
+	path = schemas
+	url = https://github.com/open-feature/schemas.git

.markdownlint-cli2.yaml

@@ -11,9 +11,14 @@ config:
       - br
   github-admonition: true
   max-one-sentence-per-line: true
+  code-block-style: false         # not compatible with mkdocs "details" panes
 
 ignores:
   - "**/CHANGELOG.md"
   - "docs/specification"
   - "node_modules"
   - "tmp"
+  - "**/protos.md"  # auto-generated
+  - "schemas"       # submodule
+  - "spec"          # submodule
+  - "test-harness"  # submodule

Makefile

@@ -9,6 +9,8 @@ ZD_CLIENT_IMG ?= zd-client:latest
 FLAGD_PROXY_IMG ?= flagd-proxy:latest
 FLAGD_PROXY_IMG_ZD ?= flagd-proxy:zd
 
+DOCS_DIR ?= web-docs
+
 workspace-init: workspace-clean
 	go work init
 	$(foreach module, $(ALL_GO_MOD_DIRS), go work use $(module);)
@@ -105,4 +107,19 @@ markdownlint:
 	$(MDL_CMD) davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md" 
 
 markdownlint-fix:
-	$(MDL_CMD) --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md" 
+	$(MDL_CMD) --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md"
+
+.PHONY: pull-schemas-submodule
+pull-schemas-submodule:
+	git submodule update schemas
+
+.PHONY: generate-proto-docs
+generate-proto-docs: pull-schemas-submodule
+	docker run --rm -v ${PWD}/$(DOCS_DIR)/reference/specifications:/out -v ${PWD}/schemas/protobuf:/protos pseudomuto/protoc-gen-doc --doc_opt=markdown,protos-with-toc.md schema/v1/schema.proto sync/v1/sync_service.proto \
+	&& echo '<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->' > ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \
+	&& sed '/^## Table of Contents/,/#top/d' ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md >> ${PWD}/$(DOCS_DIR)/reference/specifications/protos.md \
+	&& rm -f ${PWD}/$(DOCS_DIR)/reference/specifications/protos-with-toc.md
+
+.PHONY: run-web-docs
+run-web-docs: generate-docs generate-proto-docs
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

README.md

@@ -21,7 +21,7 @@
 
 ## What's flagd?
 
-Flagd is a feature flag daemon with a Unix philosophy. Think of it as a ready-made, open source, OpenFeature compliant feature flag backend system.
+Flagd is a feature flag daemon with a Unix philosophy. Think of it as a ready-made, open source, OpenFeature-compliant feature flag backend system.
 
 ## Features
 

core/go.mod

@@ -13,7 +13,7 @@ require (
 	github.com/golang/mock v1.6.0
 	github.com/open-feature/open-feature-operator v0.2.36
 	github.com/open-feature/schemas v0.2.8
-	github.com/prometheus/client_golang v1.16.0
+	github.com/prometheus/client_golang v1.17.0
 	github.com/robfig/cron v1.2.0
 	github.com/rs/cors v1.10.0
 	github.com/rs/xid v1.5.0
@@ -32,10 +32,11 @@ require (
 	go.opentelemetry.io/otel/trace v1.18.0
 	go.uber.org/zap v1.26.0
 	golang.org/x/crypto v0.13.0
+	golang.org/x/exp v0.0.0-20220722155223-a9213eeb770e
 	golang.org/x/mod v0.12.0
 	golang.org/x/net v0.15.0
 	golang.org/x/sync v0.3.0
-	google.golang.org/grpc v1.58.1
+	google.golang.org/grpc v1.58.2
 	google.golang.org/protobuf v1.31.0
 	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.28.2
@@ -81,17 +82,16 @@ require (
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/prometheus/client_model v0.4.0 // indirect
+	github.com/prometheus/client_model v0.4.1-0.20230718164431-9a2bf3000d16 // indirect
 	github.com/prometheus/common v0.44.0 // indirect
-	github.com/prometheus/procfs v0.10.1 // indirect
+	github.com/prometheus/procfs v0.11.1 // indirect
 	github.com/rogpeppe/go-internal v1.11.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlpmetric v0.41.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.0.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/exp v0.0.0-20220722155223-a9213eeb770e // indirect
 	golang.org/x/oauth2 v0.10.0 // indirect
 	golang.org/x/sys v0.12.0 // indirect
 	golang.org/x/term v0.12.0 // indirect

core/go.sum

@@ -650,14 +650,20 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_golang v1.16.0 h1:yk/hx9hDbrGHovbci4BY+pRMfSuuat626eFsHb7tmT8=
 github.com/prometheus/client_golang v1.16.0/go.mod h1:Zsulrv/L9oM40tJ7T815tM89lFEugiJ9HzIqaAx4LKc=
+github.com/prometheus/client_golang v1.17.0 h1:rl2sfwZMtSthVU752MqfjQozy7blglC+1SOtjMAMh+Q=
+github.com/prometheus/client_golang v1.17.0/go.mod h1:VeL+gMmOAxkS2IqfCq0ZmHSL+LjWfWDUmp1mBz9JgUY=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/prometheus/client_model v0.2.0/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/prometheus/client_model v0.4.0 h1:5lQXD3cAg1OXBf4Wq03gTrXHeaV0TQvGfUooCfx1yqY=
 github.com/prometheus/client_model v0.4.0/go.mod h1:oMQmHW1/JoDwqLtg57MGgP/Fb1CJEYF2imWWhWtMkYU=
+github.com/prometheus/client_model v0.4.1-0.20230718164431-9a2bf3000d16 h1:v7DLqVdK4VrYkVD5diGdl4sxJurKJEMnODWRJlxV9oM=
+github.com/prometheus/client_model v0.4.1-0.20230718164431-9a2bf3000d16/go.mod h1:oMQmHW1/JoDwqLtg57MGgP/Fb1CJEYF2imWWhWtMkYU=
 github.com/prometheus/common v0.44.0 h1:+5BrQJwiBB9xsMygAB3TNvpQKOwlkc25LbISbrdOOfY=
 github.com/prometheus/common v0.44.0/go.mod h1:ofAIvZbQ1e/nugmZGz4/qCb9Ap1VoSTIO7x0VV9VvuY=
 github.com/prometheus/procfs v0.10.1 h1:kYK1Va/YMlutzCGazswoHKo//tZVlFpKYh+PymziUAg=
 github.com/prometheus/procfs v0.10.1/go.mod h1:nwNm2aOCAYw8uTR/9bWRREkZFxAUcWzPHWJq+XBB/FM=
+github.com/prometheus/procfs v0.11.1 h1:xRC8Iq1yyca5ypa9n1EZnWZkt7dwcoRPQwX/5gwaUuI=
+github.com/prometheus/procfs v0.11.1/go.mod h1:eesXgaPo1q7lBpVMoMy0ZOFTth9hBn4W/y0/p/ScXhY=
 github.com/robfig/cron v1.2.0 h1:ZjScXvvxeQ63Dbyxy76Fj3AT3Ut0aKsyd2/tl3DTMuQ=
 github.com/robfig/cron v1.2.0/go.mod h1:JGuDeoQd7Z6yL4zQhZ3OPEVHB7fL6Ka6skscFHfmt2k=
 github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
@@ -1308,6 +1314,8 @@ google.golang.org/grpc v1.58.0 h1:32JY8YpPMSR45K+c3o6b8VL73V+rR8k+DeMIr4vRH8o=
 google.golang.org/grpc v1.58.0/go.mod h1:tgX3ZQDlNJGU96V6yHh1T/JeoBQ2TXdr43YbYSsCJk0=
 google.golang.org/grpc v1.58.1 h1:OL+Vz23DTtrrldqHK49FUOPHyY75rvFqJfXC84NYW58=
 google.golang.org/grpc v1.58.1/go.mod h1:tgX3ZQDlNJGU96V6yHh1T/JeoBQ2TXdr43YbYSsCJk0=
+google.golang.org/grpc v1.58.2 h1:SXUpjxeVF3FKrTYQI4f4KvbGD5u2xccdYdurwowix5I=
+google.golang.org/grpc v1.58.2/go.mod h1:tgX3ZQDlNJGU96V6yHh1T/JeoBQ2TXdr43YbYSsCJk0=
 google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.1.0/go.mod h1:6Kw0yEErY5E/yWrBtf03jp27GLLJujG4z/JK95pnjjw=
 google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8=
 google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0=

flagd/cmd/doc/main.go

@@ -6,7 +6,7 @@ import (
 	"github.com/open-feature/flagd/flagd/cmd"
 )
 
-const docPath = "../docs/configuration"
+const docPath = "../web-docs/reference/flagd-cli"
 
 func main() {
 	if err := cmd.GenerateDoc(docPath); err != nil {

flagd/go.mod

@@ -7,7 +7,7 @@ require (
 	github.com/dimiro1/banner v1.1.0
 	github.com/mattn/go-colorable v0.1.13
 	github.com/open-feature/flagd/core v0.6.6
-	github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.16
+	github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.17
 	github.com/open-feature/go-sdk-contrib/tests/flagd v1.3.0
 	github.com/spf13/cobra v1.7.0
 	github.com/spf13/viper v1.16.0

flagd/go.sum

@@ -686,6 +686,8 @@ github.com/open-feature/go-sdk v1.7.0 h1:g6o/sf5xaED7xawXwZ0LqE7RS9co7HZJMClXCXm
 github.com/open-feature/go-sdk v1.7.0/go.mod h1:5aV26tEoQuompRa8A6BAGukhi88pRMZsslJJwucGNzs=
 github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.16 h1:Itgdo1iSCZkHQ3A6dOzpp8fZU4MRqm9/5HiUO1+bkaQ=
 github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.16/go.mod h1:inzptmy90VfLUeKyTfqsb2/19u+Heu/ylKuCPl8mvBs=
+github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.17 h1:Ivx0USjWI2iXq20wEeEhzK+Jck2dwyGY6TxKS9aoutw=
+github.com/open-feature/go-sdk-contrib/providers/flagd v0.1.17/go.mod h1:ndXCZtJ3xvUK/MQlyHcs8gwW1UQmVMhFGV+OgcUj9TQ=
 github.com/open-feature/go-sdk-contrib/tests/flagd v1.3.0 h1:XstvqjyOAo7s0no2z7R8kN1TrIRWzXtu867h0O+gzkk=
 github.com/open-feature/go-sdk-contrib/tests/flagd v1.3.0/go.mod h1:Hb/nrUmwLdo4j+r+WwdBR0jXFaVrKdbVOHaQgq6ra2A=
 github.com/open-feature/open-feature-operator v0.2.36 h1:dzyZh9JSIRvXkfpM9ynYplNk7vjQFLs9sd5aHhF48z4=

mkdocs.yml

@@ -1,4 +1,5 @@
 site_name: flagd
+site_description: A feature flag daemon with a Unix philosophy
 theme:
   name: material
   palette: 
@@ -15,14 +16,14 @@ theme:
       toggle:
         icon: material/brightness-4
         name: Switch to light mode
-  # logo: path/to/file.png
-  # favicon: path/to/file.png
+  logo: assets/logo-white.svg
+  favicon: assets/logo-white.svg
   icon:
     repo: fontawesome/brands/github
   features:
-  #  - navigation.tabs
-   - content.action.edit
-   - content.code.copy
+    - navigation.footer
+    - content.action.edit
+    - content.code.copy
 
 docs_dir: web-docs
 repo_url: https://github.com/open-feature/flagd
@@ -32,27 +33,56 @@ markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
       # linenums: true
+      line_spans: __span
+      pygments_lang_class: true
   - pymdownx.inlinehilite
   - pymdownx.snippets
-  - pymdownx.superfences
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - tables
+  - attr_list
+  - pymdownx.emoji:
+      # we are using an older emoji extension because the newest (suggested in docs) doesn't work with Python < 3.10
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
 
 nav:
-  - 'Home': 'index.md'
+  - 'Introduction': 'index.md'
+  - 'Quick start': 'quick-start.md'
   - 'Concepts':
-      - 'Flagd concepts (start here)': 'concepts/index.md'
-      - 'Flagd architecture': 'concepts/architecture.md'
-  - 'Flagd on Kubernetes':
-      - 'Getting started with flagd on kubernetes': 'k8s/index.md'
-  - 'Flagd outside of kubernetes':
-      - 'Getting started with flagd outside of kubernetes': 'nonk8s/index.md'
-      - 'Flag merging': 'nonk8s/flagmerging.md'
-      - 'Flagd as a system service': 'nonk8s/systemservice.md'
-  - 'Kubernetes Custom Resources':
-      - 'FlagSourceConfiguration': 'k8s/crds/flagsourceconfiguration.md'
-      - 'FeatureFlagConfiguration': 'k8s/crds/featureflagconfiguration.md'
-  - 'Flagd Telemetry':
-      - 'Flagd OpenTelemetry Support': 'concepts/opentelemetry.md'
+    - 'Feature Flagging': 'concepts/feature-flagging.md'
+    - 'Syncs': 'concepts/syncs.md'
+  - 'Architecture': 'architecture.md'
+  - 'Deployment': 'deployment.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'
+    - 'Sync Configuration': 'reference/sync-configuration.md'
+    - 'Flag Definitions':
+      - 'Definition Overview': 'reference/flag-definitions.md'
+      - 'Custom Operations':
+        - 'Fractional': 'reference/custom-operations/fractional-operation.md'
+        - 'Semantic Version': 'reference/custom-operations/semver-operation.md'
+        - 'String Comparison': 'reference/custom-operations/string-comparison-operation.md'
+    - 'Providers': 'reference/providers.md'
+    - 'Monitoring': 'reference/monitoring.md'
+    - 'Specifications':
+      - 'RPC Providers': 'reference/specifications/rpc-providers.md'
+      - 'In-Process Providers': 'reference/specifications/in-process-providers.md'
+      - 'Protobuf Schemas': 'reference/specifications/protos.md' 
+      - 'Custom Operations':
+        - 'Fractional Specification': 'reference/specifications/custom-operations/fractional-operation-spec.md'
+        - 'Semantic Version Specification': 'reference/specifications/custom-operations/semver-operation-spec.md'
+        - 'String Comparison Specification': 'reference/specifications/custom-operations/string-comparison-operation-spec.md'
+    - 'Naming': 'reference/naming.md'
+  - 'FAQ': 'faq.md'
   - 'Troubleshooting': 'troubleshooting.md'
-  - 'Ecosystem and Tooling': 'ecosystem.md'
 plugins:
-  - social
+  - social