chore: docs rework

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

.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
 

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 {

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