docs: add provider to the documentation (open-feature#1027)

## This PR - adds a section on the install page that lists the available providers - includes the readmes of the available providers ### How to test - Install: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/installation/ - Overview Page: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/ - Go: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/go/ - Java: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/java/ - Node.JS: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/nodejs/ - PHP: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/php/ - .NET: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/dotnet/ - Web: https://deploy-preview-1027--polite-licorice-3db33c.netlify.app/providers/web/ --------- Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
olunusib · Jan 16, 2024 · 0f8802b · 0f8802b
1 parent dbbb7b2
commit 0f8802b
Show file tree

Hide file tree

Showing 17 changed files with 495 additions and 402 deletions.
diff --git a/.gitignore b/.gitignore
@@ -13,6 +13,7 @@ go.work
 go.work.sum
 bin/
 node_modules/
+.venv
 
 # built documentation
 site

diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -20,8 +20,9 @@ ignores:
   - "node_modules"
   - "playground-app/node_modules"
   - "tmp"
-  - "**/protos.md"     # auto-generated
-  - "docs/playground"  # auto-generated
-  - "schemas"          # submodule
-  - "spec"             # submodule
-  - "test-harness"     # submodule
+  - "**/protos.md"           # auto-generated
+  - "docs/playground"        # auto-generated
+  - "docs/providers/*.md"    # auto-generated
+  - "schemas"                # submodule
+  - "spec"                   # submodule
+  - "test-harness"           # submodule
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,2 @@
+FROM squidfunk/mkdocs-material:9.5
+RUN pip install mkdocs-include-markdown-plugin
diff --git a/Makefile b/Makefile
@@ -123,7 +123,8 @@ generate-proto-docs: pull-schemas-submodule
 
 .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
+	docker build -t squidfunk/mkdocs-material . \
+	&& docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
 
 # Run the playground app in dev mode
 # See the readme in the playground-app folder for more details

diff --git a/docs/installation.md b/docs/installation.md
@@ -18,7 +18,7 @@ docker pull ghcr.io/open-feature/flagd:latest
 FROM ghcr.io/open-feature/flagd:latest
 ```
 
-### Kubernetes
+## Kubernetes
 
 flagd was designed with cloud-native paradigms in mind.
 You can run it as a sidecar, or as a central service in your cluster.
@@ -50,31 +50,7 @@ brew install flagd
 go install github.com/open-feature/flagd/flagd@latest
 ```
 
----
-
-## In-Process
-
-### :fontawesome-brands-golang: Go in-process provider
-
-[flagd-in-process/pkg](https://pkg.go.dev/github.com/open-feature/go-sdk-contrib/providers/flagd-in-process/pkg)
-
-```shell
-go get github.com/open-feature/go-sdk-contrib/providers/flagd-in-process/pkg@latest
-```
+## Summary
 
-### :fontawesome-brands-java: Java in-process provider
-
-#### Maven
-
-```xml
-<dependency>
-  <groupId>dev.openfeature.contrib.providers</groupId>
-  <artifactId>flagd</artifactId>
-</dependency>
-```
-
-#### Gradle
-
-```gradle
-implementation 'dev.openfeature.contrib.providers:flagd'
-```
+Once flagd is installed, you can start using it within your application.
+Check out the [OpenFeature providers page](./providers/index.md) to learn more.
diff --git a/docs/providers/dotnet.md b/docs/providers/dotnet.md
@@ -0,0 +1,8 @@
+# .NET provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/dotnet-sdk-contrib/main/src/OpenFeature.Contrib.Providers.Flagd/README.md"
+  start="## Install dependencies"
+%}
diff --git a/docs/providers/go.md b/docs/providers/go.md
@@ -0,0 +1,9 @@
+# Go provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/go-sdk-contrib/main/providers/flagd/README.md"
+  start="## Installation"
+  end="## License"
+%}
diff --git a/docs/providers/index.md b/docs/providers/index.md
@@ -0,0 +1,25 @@
+---
+title: OpenFeature Providers
+description: Overview of the available flagd providers compatible with OpenFeature.
+---
+
+flagd was built from the ground up to be [Openfeature-compliant](../concepts/feature-flagging.md#openfeature-compliance).
+To use it in your application, you must use the [OpenFeature SDK](https://openfeature.dev/docs/reference/technologies/) for your language, along with the associated OpenFeature _provider_.
+For more information about Openfeature providers, see the [OpenFeature documentation](https://openfeature.dev/docs/reference/concepts/provider).
+
+## Providers
+
+Providers for flagd come in two flavors: those that are built to communicate with a flagd instance (over HTTP or gRPC) and those that embed flagd's evaluation engine directly (note that some providers are capable of operating in either mode). For more information on how to deploy and use flagd, see [architecture](../architecture.md) and [installation](../installation.md).
+
+The following table lists all the available flagd providers.
+
+| Technology                                                    | RPC              | in-process       |
+| ------------------------------------------------------------- | ---------------- | ---------------- |
+| :fontawesome-brands-golang: [Go](./go.md)           | :material-check: | :material-check: |
+| :fontawesome-brands-java: [Java](./java.md)         | :material-check: | :material-check: |
+| :fontawesome-brands-node-js: [Node.JS](./nodejs.md) | :material-check: | :material-check: |
+| :simple-php: [PHP](./php.md)                        | :material-check: | :material-close: |
+| :simple-dotnet: [.NET](./dotnet.md)                 | :material-check: | :material-close: |
+| :material-web: [Web](./web.md)                      | :material-check: | :material-close: |
+
+For information on implementing a flagd provider, see the specifications for [RPC](../reference/specifications/rpc-providers.md) and [in-process](../reference/specifications/in-process-providers.md) providers.
diff --git a/docs/providers/java.md b/docs/providers/java.md
@@ -0,0 +1,8 @@
+# Java provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/java-sdk-contrib/main/providers/flagd/README.md"
+  start="## Installation"
+%}
diff --git a/docs/providers/nodejs.md b/docs/providers/nodejs.md
@@ -0,0 +1,9 @@
+# Node.js provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/js-sdk-contrib/main/libs/providers/flagd/README.md"
+  start="## Installation"
+  end="## Building"
+%}
diff --git a/docs/providers/php.md b/docs/providers/php.md
@@ -0,0 +1,8 @@
+# PHP provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/php-sdk-contrib/main/providers/Flagd/README.md"
+  start="## Installation"
+%}
diff --git a/docs/providers/web.md b/docs/providers/web.md
@@ -0,0 +1,10 @@
+
+# Web provider
+
+## Installation
+
+{%
+  include "https://raw.githubusercontent.com/open-feature/js-sdk-contrib/main/libs/providers/flagd-web/README.md"
+  start="## Installation"
+  end="## Building"
+%}
diff --git a/docs/reference/providers.md b/docs/reference/providers.md
diff --git a/docs/reference/specifications/rpc-providers.md b/docs/reference/specifications/rpc-providers.md
@@ -1,5 +1,5 @@
 ---
-description: flagd RPC proivider specification
+description: flagd RPC provider specification
 ---
 
 # Creating an RPC flagd provider
@@ -12,7 +12,7 @@ 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](../providers.md))
+- Proficiency in the chosen programming language (check the language isn't already covered by the [existing providers](../../providers/index.md))
 
 ## flagd Evaluation API
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -31,6 +31,10 @@ theme:
     - search.suggest
     - search.highlight
     - search.share
+    - content.tooltips
+    - navigation.instant
+    - navigation.tracking
+    - navigation.indexes
 extra_css:
   - assets/extra.css
 
@@ -45,7 +49,8 @@ markdown_extensions:
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
-  - pymdownx.snippets
+  - pymdownx.snippets:
+      url_download: true
   - admonition
   - pymdownx.details
   - pymdownx.superfences:
@@ -57,9 +62,8 @@ markdown_extensions:
   - attr_list
   - md_in_html
   - 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
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 
 nav:
   - 'Introduction': 'index.md'
@@ -70,6 +74,14 @@ nav:
     - 'Feature Flagging': 'concepts/feature-flagging.md'
     - 'Syncs': 'concepts/syncs.md'
   - 'Architecture': 'architecture.md'
+  - 'OpenFeature Providers':
+    - 'providers/index.md'
+    - 'Go': 'providers/go.md'
+    - 'Java': 'providers/java.md'
+    - 'Node.JS': 'providers/nodejs.md'
+    - 'PHP': 'providers/php.md'
+    - '.NET': 'providers/dotnet.md'
+    - 'Web': 'providers/web.md'
   - 'Reference':
     - 'CLI':
       - 'Overview': 'reference/flagd-cli/flagd.md'
@@ -82,7 +94,6 @@ nav:
         - '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'
@@ -101,4 +112,10 @@ nav:
   - 'Troubleshooting': 'troubleshooting.md'
 plugins:
   - social
-  - search
+  - search
+  # https://github.com/mondeja/mkdocs-include-markdown-plugin
+  - include-markdown
+  # https://github.com/mkdocs/mkdocs-redirects
+  - redirects:
+      redirect_maps:
+        'reference/providers.md': 'providers/index.md'
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,6 +13,7 @@ go.work @@
     go.work.sum
     bin/
     node_modules/
+    .venv
     # built documentation
     site
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		FROM squidfunk/mkdocs-material:9.5
		RUN pip install mkdocs-include-markdown-plugin