From c9026395b761b98ff4c6c72af3efa9dd03ba16bf Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 5 Jan 2022 10:35:50 +0100 Subject: [PATCH 01/32] docs: add initial extra doc categories. --- website/sidebars.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/website/sidebars.js b/website/sidebars.js index 65f2abc028..5dd6d1d386 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -11,6 +11,8 @@ module.exports = { documentation: { + 'Tutorials': [ 'user_guide/index'], + 'Reference documentation': [ 'user_guide/index'], 'Getting started': [ 'user_guide/index', 'user_guide/quickstart', From 24e614c977392f9eb206b7a5835df3464f948392 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 5 Jan 2022 13:42:15 +0100 Subject: [PATCH 02/32] docs: start restructuring the docs landing page. --- website/docs/user_guide/index.md | 44 +++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index d870431903..e82dbb3fd2 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -5,9 +5,47 @@ slug: / sidebar_position: 1 --- -Welcome to the Unleash documentation. Our goal with our documentation is to guide you through the most essential concepts of Unleash. +:::note +The docs are currently undergoing some heavy restructuring and development ๐Ÿ‘ทโ€โ™€๏ธ๐Ÿ‘ท๐Ÿฝ If something is unclear, don't hesitate to [let us know on Slack](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE)! +::: -One of the most important aspects of the architecture to understand is that feature toggles _are evaluated in a client SDKs_ which runs as part of your application. This makes toggle evaluations super-fast (_we talk nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable). +Welcome to the Unleash documentation, your one-stop shop to everything Unleash. Whether you're just getting started or have been using Unleash for years, you should be able to find answers to all your questions here. + +## Getting help + +Have questions that you can't find the answer to in these docs? You can always turn to [the Unleash Slack community](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE) and ask us questions directly (or just come and hang out ๐Ÿ˜„). + +## Documentation structure + +Our documentation is split into four parts, using the [Diataxis documentation framework](https://diataxis.fr/): documentation, how-to guides, topic guides, and reference documentation. + +### Tutorials + +New to Unleash? Not sure where to get started? The tutorials guide you through taking your first steps with Unleash. + +### How-to guides + +Our how-to guides show you how to perform a number of common tasks that you'll want to do. Think of them as recipes. They are more advanced than the tutorials and assume you have some working knowledge of Unleash. + +### Topic guides + +Topic guides discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts. + +### Reference documentation + +The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts. + +## Other resources and communities + +๐Ÿ’ป The core of Unleash is all open source and [hosted on GitHub](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash "Unleash on GitHub"). + +๐Ÿ’ฌ If you've got questions or just wanna chat to the team and other Unleash users, come [join our Slack community](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE) + +๐Ÿฆ You can also follow us [on Twitter](https://twitter.com/getunleash "Unleash on Twitter"), [LinkedIn](https://www.linkedin.com/company/getunleash/ "Unleash on LinkedIn"), or [Instagram](https://www.instagram.com/getunleash/ "Unleash on Instagram") for more updates and extra content. + +Our goal with our documentation is to guide you through the most essential concepts of Unleash. + +One of the most important aspects of the architecture to understand is that feature toggles _are evaluated in a client SDKs_ which runs as part of your application. This makes toggle evaluations super-fast (_we're talk nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable). If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture). @@ -32,4 +70,4 @@ Before you can connect your application to Unleash you need a Unleash server. Yo - **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. [See all our SDKs](sdks/index.md) - **Unleash Proxy** - Sits between frontend/native applications and the Unleash API. Ensures high performance and that you don't expose the full feature toggle configuration to end-users. [Read more about Unleash Proxy](sdks/unleash-proxy.md) -To be super fast (_we talk nano-seconds_), the [client SDK](sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database. +To be super fast (_we're talking nano-seconds_), the [client SDK](sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database. From b3c28de0bb1a337deb4dca03298dab13554d2b2f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 25 Jan 2022 12:20:53 +0100 Subject: [PATCH 03/32] docs: add introduction as separate entry --- website/sidebars.js | 165 ++++++++++++++++++++------------------------ 1 file changed, 73 insertions(+), 92 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 5dd6d1d386..0e4cd3566a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -10,97 +10,78 @@ */ module.exports = { - documentation: { - 'Tutorials': [ 'user_guide/index'], - 'Reference documentation': [ 'user_guide/index'], - 'Getting started': [ - 'user_guide/index', - 'user_guide/quickstart', - 'user_guide/important-concepts', - 'user_guide/v4-whats-new', - 'user_guide/create_feature_toggle', - 'user_guide/activation_strategy', - 'user_guide/control_rollout', - 'user_guide/projects', - 'user_guide/environments', - 'user_guide/unleash_context', - 'user_guide/user-management', - 'user_guide/rbac', - 'user_guide/api-token', - 'user_guide/technical_debt', - ], - 'Unleash SDKs': [ - 'sdks/index', - 'sdks/unleash-proxy', - { - type: 'category', - collapsible: false, - label: 'Server-side SDKs', - items: [ - 'sdks/go_sdk', - 'sdks/java_sdk', - 'sdks/node_sdk', - 'sdks/php_sdk', - 'sdks/python_sdk', - 'sdks/ruby_sdk', - { - type: 'link', - href: 'https://github.com/unleash/unleash-client-rust', - label: 'Rust SDK', - }, - 'sdks/dot_net_sdk', - ], - }, - { - type: 'category', - collapsible: false, - label: 'Client-side SDKs', - items: [ - 'sdks/android_proxy_sdk', - 'sdks/proxy-ios', - 'sdks/proxy-javascript', - 'sdks/proxy-react', - ], - }, - { - type: 'link', - label: 'Community SDKs', - href: '/sdks#community-sdks', - }, - ], - Addons: [ - 'addons/index', - 'addons/webhook', - 'addons/slack', - 'addons/teams', - 'addons/datadog', - ], - Advanced: [ - 'advanced/strategy_constraints', - 'advanced/custom_activation_strategy', - 'advanced/feature_toggle_types', - 'advanced/toggle_variants', - 'advanced/stickiness', - 'advanced/archived_toggles', - 'advanced/audit_log', - 'advanced/api_access', - 'advanced/tags', - 'advanced/enterprise-authentication', - 'advanced/sso-open-id-connect', - 'advanced/sso-saml', - 'advanced/sso-saml-keycloak', - 'advanced/sso-google', - ], - 'Topic guides': [ - 'topics/a-b-testing' - ], - "How-to guides": [ - "how-to/how-to-add-strategy-constraints", - "how-to/how-to-create-and-assign-custom-project-roles", - "how-to/how-to-define-custom-context-fields", - "how-to/how-to-use-custom-strategies", - ] - }, + documentation: [ + 'user_guide/index', + { + Tutorials: ['user_guide/index'], + 'Reference documentation': ['user_guide/index'], + 'Getting started': [ + 'user_guide/index', + 'user_guide/quickstart', + 'user_guide/important-concepts', + 'user_guide/v4-whats-new', + 'user_guide/create_feature_toggle', + 'user_guide/activation_strategy', + 'user_guide/control_rollout', + 'user_guide/projects', + 'user_guide/environments', + 'user_guide/unleash_context', + 'user_guide/user-management', + 'user_guide/rbac', + 'user_guide/api-token', + 'user_guide/technical_debt', + ], + 'Unleash SDKs': [ + 'sdks/index', + 'sdks/java_sdk', + 'sdks/node_sdk', + 'sdks/dot_net_sdk', + 'sdks/go_sdk', + 'sdks/python_sdk', + 'sdks/ruby_sdk', + 'sdks/php_sdk', + 'sdks/unleash-proxy', + 'sdks/android_proxy_sdk', + 'sdks/proxy-javascript', + 'sdks/proxy-react', + 'sdks/proxy-ios', + { + label: 'Community SDKs', + type: 'link', + href: '/sdks#community-sdks', + }, + ], + Addons: [ + 'addons/index', + 'addons/webhook', + 'addons/slack', + 'addons/teams', + 'addons/datadog', + ], + Advanced: [ + 'advanced/strategy_constraints', + 'advanced/custom_activation_strategy', + 'advanced/feature_toggle_types', + 'advanced/toggle_variants', + 'advanced/stickiness', + 'advanced/archived_toggles', + 'advanced/audit_log', + 'advanced/api_access', + 'advanced/tags', + 'advanced/enterprise-authentication', + 'advanced/sso-open-id-connect', + 'advanced/sso-saml', + 'advanced/sso-saml-keycloak', + 'advanced/sso-google', + ], + 'Topic guides': ['topics/a-b-testing'], + 'How-to guides': [ + 'how-to/how-to-add-strategy-constraints', + 'how-to/how-to-define-custom-context-fields', + 'how-to/how-to-use-custom-strategies', + ], + }, + ], api: { Introduction: [ 'api/index', @@ -146,6 +127,6 @@ module.exports = { 'Jira server': [ 'integrations/jira_server_plugin_installation', 'integrations/jira_server_plugin_usage', - ] + ], }, }; From 19eea8b3a270c33593eb24d971cd75e13a666cac Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 11 Jan 2022 13:25:51 +0100 Subject: [PATCH 04/32] docs: rename doc introduction. --- website/docs/user_guide/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index e82dbb3fd2..2c85e1ca53 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -1,6 +1,6 @@ --- id: index -title: Introduction +title: About the docs ๐Ÿ“š slug: / sidebar_position: 1 --- From 4f0fa7cfd2894a75c90a0cf4e2fb2d61c9502891 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 11 Jan 2022 13:43:19 +0100 Subject: [PATCH 05/32] docs: move addons and (most) api docs to reference --- website/sidebars.js | 64 +++++++++++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 0e4cd3566a..fcf730d08b 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,10 +13,42 @@ module.exports = { documentation: [ 'user_guide/index', { - Tutorials: ['user_guide/index'], - 'Reference documentation': ['user_guide/index'], + Tutorials: [], + 'Reference documentation': [ + { + type: 'category', + link: { type: 'doc', id: 'addons/index' }, + items: [ + 'addons/webhook', + 'addons/slack', + 'addons/teams', + 'addons/datadog', + ], + label: 'Addons', + }, + { + 'Admin API': [ + 'api/admin/features', + 'api/admin/projects', + 'api/admin/feature-toggles-v2', + 'api/admin/features-archive', + 'api/admin/strategies', + 'api/admin/metrics', + 'api/admin/events', + 'api/admin/state', + 'api/admin/feature-types', + 'api/admin/addons', + 'api/admin/context', + 'api/admin/user-admin', + ], + 'Client SDK API': [ + 'api/client/features', + 'api/client/register', + 'api/client/metrics', + ], + }, + ], 'Getting started': [ - 'user_guide/index', 'user_guide/quickstart', 'user_guide/important-concepts', 'user_guide/v4-whats-new', @@ -51,13 +83,6 @@ module.exports = { href: '/sdks#community-sdks', }, ], - Addons: [ - 'addons/index', - 'addons/webhook', - 'addons/slack', - 'addons/teams', - 'addons/datadog', - ], Advanced: [ 'advanced/strategy_constraints', 'advanced/custom_activation_strategy', @@ -89,25 +114,6 @@ module.exports = { 'api/internal/health', 'api/open_api', ], - 'Admin API': [ - 'api/admin/features', - 'api/admin/projects', - 'api/admin/feature-toggles-v2', - 'api/admin/features-archive', - 'api/admin/strategies', - 'api/admin/metrics', - 'api/admin/events', - 'api/admin/state', - 'api/admin/feature-types', - 'api/admin/addons', - 'api/admin/context', - 'api/admin/user-admin', - ], - 'Client SDK API': [ - 'api/client/features', - 'api/client/register', - 'api/client/metrics', - ], }, 'Deploy and manage': { 'Deploy & configure': [ From 8828523e4db80293f7a3379755b6972a20fe90f4 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 11 Jan 2022 14:54:37 +0100 Subject: [PATCH 06/32] docs: move sdks to reference docs --- website/sidebars.js | 68 ++++++++++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index fcf730d08b..cf8effa54e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,8 +13,10 @@ module.exports = { documentation: [ 'user_guide/index', { - Tutorials: [], - 'Reference documentation': [ + label: 'Reference documentation', + type: 'category', + collapsible: false, + items: [ { type: 'category', link: { type: 'doc', id: 'addons/index' }, @@ -41,13 +43,47 @@ module.exports = { 'api/admin/context', 'api/admin/user-admin', ], - 'Client SDK API': [ + 'Client API': [ 'api/client/features', 'api/client/register', 'api/client/metrics', ], + 'Client SDKs': [ + 'sdks/index', + 'sdks/java_sdk', + 'sdks/node_sdk', + 'sdks/dot_net_sdk', + 'sdks/go_sdk', + 'sdks/python_sdk', + 'sdks/ruby_sdk', + 'sdks/php_sdk', + 'sdks/unleash-proxy', + 'sdks/android_proxy_sdk', + 'sdks/proxy-javascript', + 'sdks/proxy-react', + 'sdks/proxy-ios', + { + label: 'Community SDKs', + type: 'link', + href: '/sdks#community-sdks', + }, + , + ], }, ], + }, + { + label: 'How-to guides', + type: 'category', + collapsible: true, + items: [ + 'how-to/how-to-add-strategy-constraints', + 'how-to/how-to-define-custom-context-fields', + 'how-to/how-to-use-custom-strategies', + ], + }, + { + Tutorials: [], 'Getting started': [ 'user_guide/quickstart', 'user_guide/important-concepts', @@ -63,26 +99,6 @@ module.exports = { 'user_guide/api-token', 'user_guide/technical_debt', ], - 'Unleash SDKs': [ - 'sdks/index', - 'sdks/java_sdk', - 'sdks/node_sdk', - 'sdks/dot_net_sdk', - 'sdks/go_sdk', - 'sdks/python_sdk', - 'sdks/ruby_sdk', - 'sdks/php_sdk', - 'sdks/unleash-proxy', - 'sdks/android_proxy_sdk', - 'sdks/proxy-javascript', - 'sdks/proxy-react', - 'sdks/proxy-ios', - { - label: 'Community SDKs', - type: 'link', - href: '/sdks#community-sdks', - }, - ], Advanced: [ 'advanced/strategy_constraints', 'advanced/custom_activation_strategy', @@ -100,11 +116,7 @@ module.exports = { 'advanced/sso-google', ], 'Topic guides': ['topics/a-b-testing'], - 'How-to guides': [ - 'how-to/how-to-add-strategy-constraints', - 'how-to/how-to-define-custom-context-fields', - 'how-to/how-to-use-custom-strategies', - ], + 'How-to guides': [], }, ], api: { From ca7657e424c147e1447958b7157ab9a79db79753 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 11 Jan 2022 14:54:47 +0100 Subject: [PATCH 07/32] docs: change title of addons index doc. --- website/docs/addons/addons.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/addons/addons.md b/website/docs/addons/addons.md index 7422ea4a70..9402d20e3b 100644 --- a/website/docs/addons/addons.md +++ b/website/docs/addons/addons.md @@ -1,6 +1,6 @@ --- id: index -title: Introduction +title: Addons --- > This feature was introduced in _Unleash v3.11.0_. From 28934042c0f7231d6c77030dfb1548cd63f90e78 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 11 Jan 2022 15:06:32 +0100 Subject: [PATCH 08/32] docs: re-categorize most current docs --- website/sidebars.js | 69 +++++++++++++++++++++++---------------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index cf8effa54e..ac7660e79e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,7 +13,7 @@ module.exports = { documentation: [ 'user_guide/index', { - label: 'Reference documentation', + label: 'Reference documentation ๐Ÿ“œ', type: 'category', collapsible: false, items: [ @@ -67,55 +67,56 @@ module.exports = { type: 'link', href: '/sdks#community-sdks', }, - , + ], + 'Unleash concepts': [ + 'user_guide/activation_strategy', + 'user_guide/control_rollout', + 'user_guide/projects', + 'user_guide/environments', + 'user_guide/unleash_context', + 'user_guide/rbac', + 'user_guide/technical_debt', + 'advanced/strategy_constraints', + 'advanced/custom_activation_strategy', + 'advanced/feature_toggle_types', + 'advanced/toggle_variants', + 'advanced/stickiness', + 'advanced/archived_toggles', + 'advanced/audit_log', + 'advanced/tags', + 'advanced/enterprise-authentication', ], }, ], }, { - label: 'How-to guides', + label: 'How-to guides ๐Ÿฆถ', type: 'category', collapsible: true, items: [ 'how-to/how-to-add-strategy-constraints', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', - ], - }, - { - Tutorials: [], - 'Getting started': [ - 'user_guide/quickstart', - 'user_guide/important-concepts', - 'user_guide/v4-whats-new', - 'user_guide/create_feature_toggle', - 'user_guide/activation_strategy', - 'user_guide/control_rollout', - 'user_guide/projects', - 'user_guide/environments', - 'user_guide/unleash_context', - 'user_guide/user-management', - 'user_guide/rbac', - 'user_guide/api-token', - 'user_guide/technical_debt', - ], - Advanced: [ - 'advanced/strategy_constraints', - 'advanced/custom_activation_strategy', - 'advanced/feature_toggle_types', - 'advanced/toggle_variants', - 'advanced/stickiness', - 'advanced/archived_toggles', - 'advanced/audit_log', - 'advanced/api_access', - 'advanced/tags', - 'advanced/enterprise-authentication', + 'advanced/sso-open-id-connect', 'advanced/sso-saml', 'advanced/sso-saml-keycloak', 'advanced/sso-google', + 'advanced/api_access', + 'user_guide/api-token', + 'user_guide/user-management', + 'user_guide/create_feature_toggle', ], - 'Topic guides': ['topics/a-b-testing'], + }, + { + Tutorials: [], + 'Getting started ๐Ÿ': [ + 'user_guide/quickstart', + 'user_guide/important-concepts', + 'user_guide/v4-whats-new', + ], + Advanced: [], + 'Topic guides ๐Ÿค“': ['topics/a-b-testing'], 'How-to guides': [], }, ], From 4848104ec8061bd4c6432884bcc3d656f7c2f745 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 12 Jan 2022 11:44:14 +0100 Subject: [PATCH 09/32] docs: move all docs into sidebar --- website/docs/user_guide/index.md | 29 ---- website/docs/user_guide/unleash_overview.md | 30 ++++ website/sidebars.js | 157 +++++++++++--------- 3 files changed, 114 insertions(+), 102 deletions(-) create mode 100644 website/docs/user_guide/unleash_overview.md diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 2c85e1ca53..8eae6928ea 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -42,32 +42,3 @@ The reference docs contain technical reference for Unleash and the API. Go here ๐Ÿ’ฌ If you've got questions or just wanna chat to the team and other Unleash users, come [join our Slack community](https://join.slack.com/t/unleash-community/shared_invite/enQtNjUxMjU2MDc0MTAxLTJjYmViYjkwYmE0ODVlNmY1YjcwZGRmZWU5MTU1YTQ1Nzg5ZWQ2YzBlY2U1MjlmZDg5ZDRmZTMzNmQ5YmEyOGE) ๐Ÿฆ You can also follow us [on Twitter](https://twitter.com/getunleash "Unleash on Twitter"), [LinkedIn](https://www.linkedin.com/company/getunleash/ "Unleash on LinkedIn"), or [Instagram](https://www.instagram.com/getunleash/ "Unleash on Instagram") for more updates and extra content. - -Our goal with our documentation is to guide you through the most essential concepts of Unleash. - -One of the most important aspects of the architecture to understand is that feature toggles _are evaluated in a client SDKs_ which runs as part of your application. This makes toggle evaluations super-fast (_we're talk nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable). - -If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture). - -### Unleash Server {#unleash-server} - -Before you can connect your application to Unleash you need a Unleash server. You have a few options available: - -1. **Unleash Open-source** - - [Docker](deploy/getting_started) - - [Helm Chart](https://github.com/unleash/helm-charts/) - - [Click-to-deploy on Heroku](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash) -2. **Unleash Enterprise** - - [Hosted Plans](https://www.getunleash.io/plans) - - [Self-hosted](https://www.getunleash.io/blog/self-host-your-feature-toggle-system) - -### System Overview {#system-overview} - -![system_overview](/img/Unleash_architecture.svg 'System Overview') - -- **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get. [API documentation](/api) -- **Unleash Admin UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc. [Create your first feature toggle](user_guide/create-feature-toggle.md) -- **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. [See all our SDKs](sdks/index.md) -- **Unleash Proxy** - Sits between frontend/native applications and the Unleash API. Ensures high performance and that you don't expose the full feature toggle configuration to end-users. [Read more about Unleash Proxy](sdks/unleash-proxy.md) - -To be super fast (_we're talking nano-seconds_), the [client SDK](sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database. diff --git a/website/docs/user_guide/unleash_overview.md b/website/docs/user_guide/unleash_overview.md new file mode 100644 index 0000000000..d427e266e9 --- /dev/null +++ b/website/docs/user_guide/unleash_overview.md @@ -0,0 +1,30 @@ +--- +title: Unleash introductory overview +--- + +One of the most important aspects of the architecture to understand is that feature toggles _are evaluated in a client SDKs_ which runs as part of your application. This makes toggle evaluations super-fast (_we're talk nano-seconds_), scalable and resilient against network disturbances. In order to achieve this Unleash compromises a small update-delay when you change your toggle configurations until it is fully propagated to your application (in terms of seconds and is configurable). + +If you want more details you can read about [our unique architecture](https://www.getunleash.io/blog/our-unique-architecture). + +### Unleash Server {#unleash-server} + +Before you can connect your application to Unleash you need a Unleash server. You have a few options available: + +1. **Unleash Open-source** + - [Docker](deploy/getting_started) + - [Helm Chart](https://github.com/unleash/helm-charts/) + - [Click-to-deploy on Heroku](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash) +2. **Unleash Enterprise** + - [Hosted Plans](https://www.getunleash.io/plans) + - [Self-hosted](https://www.getunleash.io/blog/self-host-your-feature-toggle-system) + +### System Overview {#system-overview} + +![system_overview](/img/Unleash_architecture.svg 'System Overview') + +- **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get. [API documentation](/api) +- **Unleash Admin UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc. [Create your first feature toggle](user_guide/create-feature-toggle.md) +- **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. [See all our SDKs](sdks/index.md) +- **Unleash Proxy** - Sits between frontend/native applications and the Unleash API. Ensures high performance and that you don't expose the full feature toggle configuration to end-users. [Read more about Unleash Proxy](sdks/unleash-proxy.md) + +To be super fast (_we're talking nano-seconds_), the [client SDK](sdks/index.md) caches all feature toggles and their current configuration in memory. The activation strategies are also implemented in the SDK. This makes it really fast to check if a toggle is on or off because it is just a simple function operating on local state, without the need to poll data from the database. diff --git a/website/sidebars.js b/website/sidebars.js index ac7660e79e..8b60878b4e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -12,6 +12,33 @@ module.exports = { documentation: [ 'user_guide/index', + { + 'First steps ๐Ÿ‘ถ': [ + 'user_guide/unleash_overview', + 'user_guide/important-concepts', + 'user_guide/quickstart', + 'user_guide/v4-whats-new', + ], + }, + { + label: 'How-to guides ๐Ÿชœ', + type: 'category', + collapsible: true, + items: [ + 'how-to/how-to-add-strategy-constraints', + 'how-to/how-to-define-custom-context-fields', + 'how-to/how-to-use-custom-strategies', + + 'advanced/sso-open-id-connect', + 'advanced/sso-saml', + 'advanced/sso-saml-keycloak', + 'advanced/sso-google', + 'advanced/api_access', + 'user_guide/api-token', + 'user_guide/user-management', + 'user_guide/create_feature_toggle', + ], + }, { label: 'Reference documentation ๐Ÿ“œ', type: 'category', @@ -29,25 +56,39 @@ module.exports = { label: 'Addons', }, { - 'Admin API': [ - 'api/admin/features', - 'api/admin/projects', - 'api/admin/feature-toggles-v2', - 'api/admin/features-archive', - 'api/admin/strategies', - 'api/admin/metrics', - 'api/admin/events', - 'api/admin/state', - 'api/admin/feature-types', - 'api/admin/addons', - 'api/admin/context', - 'api/admin/user-admin', - ], - 'Client API': [ - 'api/client/features', - 'api/client/register', - 'api/client/metrics', + type: 'category', + link: { type: 'doc', id: 'api/index' }, + label: 'APIs', + items: [ + { + 'Admin API': [ + 'api/admin/addons', + 'api/admin/context', + 'api/admin/events', + 'api/admin/feature-toggles-v2', + 'api/admin/feature-types', + 'api/admin/features', + 'api/admin/features-archive', + 'api/admin/metrics', + 'api/admin/projects', + 'api/admin/state', + 'api/admin/strategies', + 'api/admin/user-admin', + ], + 'Client API': [ + 'api/client/features', + 'api/client/metrics', + 'api/client/register', + ], + 'System API': [ + 'api/internal/internal', + 'api/internal/health', + ], + }, + 'api/open_api', ], + }, + { 'Client SDKs': [ 'sdks/index', 'sdks/java_sdk', @@ -86,66 +127,36 @@ module.exports = { 'advanced/tags', 'advanced/enterprise-authentication', ], + 'Deploy and manage Unleash': [ + 'deploy/getting_started', + 'deploy/configuring_unleash', + 'deploy/securing_unleash', + 'deploy/email', + 'deploy/google_auth', + 'deploy/database-setup', + 'deploy/database_backup', + 'deploy/migration_guide', + 'deploy/import_export', + ], + }, + { + type: 'category', + label: 'Integrations', + link: { type: 'doc', id: 'integrations/integrations' }, + items: [ + { + 'Jira Server': [ + 'integrations/jira_server_plugin_installation', + 'integrations/jira_server_plugin_usage', + ], + }, + , + ], }, ], }, { - label: 'How-to guides ๐Ÿฆถ', - type: 'category', - collapsible: true, - items: [ - 'how-to/how-to-add-strategy-constraints', - 'how-to/how-to-define-custom-context-fields', - 'how-to/how-to-use-custom-strategies', - - 'advanced/sso-open-id-connect', - 'advanced/sso-saml', - 'advanced/sso-saml-keycloak', - 'advanced/sso-google', - 'advanced/api_access', - 'user_guide/api-token', - 'user_guide/user-management', - 'user_guide/create_feature_toggle', - ], - }, - { - Tutorials: [], - 'Getting started ๐Ÿ': [ - 'user_guide/quickstart', - 'user_guide/important-concepts', - 'user_guide/v4-whats-new', - ], - Advanced: [], 'Topic guides ๐Ÿค“': ['topics/a-b-testing'], - 'How-to guides': [], }, ], - api: { - Introduction: [ - 'api/index', - 'api/internal/internal', - 'api/internal/health', - 'api/open_api', - ], - }, - 'Deploy and manage': { - 'Deploy & configure': [ - 'deploy/getting_started', - 'deploy/configuring_unleash', - 'deploy/securing_unleash', - 'deploy/email', - 'deploy/google_auth', - 'deploy/database-setup', - 'deploy/database_backup', - 'deploy/migration_guide', - 'deploy/import_export', - ], - }, - Integrations: { - Integrations: ['integrations/integrations'], - 'Jira server': [ - 'integrations/jira_server_plugin_installation', - 'integrations/jira_server_plugin_usage', - ], - }, }; From d3d9d440497c02ae2dc053f5a739e0f37b854ea3 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 12 Jan 2022 11:44:34 +0100 Subject: [PATCH 10/32] docs: remove 'what's new in v4' --- website/sidebars.js | 1 - 1 file changed, 1 deletion(-) diff --git a/website/sidebars.js b/website/sidebars.js index 8b60878b4e..042dd5a53c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -17,7 +17,6 @@ module.exports = { 'user_guide/unleash_overview', 'user_guide/important-concepts', 'user_guide/quickstart', - 'user_guide/v4-whats-new', ], }, { From 50d0f3914023b5800de2590adf17e4c5f31db40e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 13 Jan 2022 11:04:32 +0100 Subject: [PATCH 11/32] docs: add content from control rollout to activation strategies The two documents covered almost the exact same things (and even had the same text. verbatim!). --- .../docs/user_guide/activation-strategies.md | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/website/docs/user_guide/activation-strategies.md b/website/docs/user_guide/activation-strategies.md index 53cdd5891f..0fd6d7bdfd 100644 --- a/website/docs/user_guide/activation-strategies.md +++ b/website/docs/user_guide/activation-strategies.md @@ -7,7 +7,13 @@ It is powerful to be able to turn a feature on and off instantaneously, without The definition of an activation strategy lives in the Unleash API and can be created via the Unleash UI. The implementation of activation strategies lives in various client implementations. -Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](unleash-context.md), which gives the necessary context for Unleash. +Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](unleash-context.md), which gives the necessary context for Unleash. The built-in activation strategies are: + +- [Standard](#standard) +- [UserIDs](#userids) +- [Gradual Rollout](#gradual-rollout) +- [IPs](#ips) +- [Hostnames](#hostnames) ## Standard {#standard} @@ -80,7 +86,18 @@ This strategy has the following modelling name in the code: - **applicationHostname** -## gradualRolloutUserId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutuserid-deprecated-from-v4---use-gradual-rollout-instead} + +## Multiple activation strategies {#multiple-activation-strategies} + +You can apply as many activation strategies to a toggle as you want. When a toggle has multiple strategies, Unleash will check each strategy in isolation. If any one of the strategies would enable the toggle for the current user, then the toggle is enabled. + +As an example, consider a case where you want to roll a feature out to 75% of your users. However, you also want to make sure that the you and your product lead get access to the feature. To achieve this, you would apply a **gradual rollout** strategy and set it to 75%. Additionally, you would add a **user IDs** strategy and add `engineer@mycompany.com` and `productlead@mycompany.com`. + +![A feature toggle with two active strategies: a user ID strategy and a gradual rollout strategy. The strategies are configured as described in the preceding paragraph.](/img/control_rollout_multiple_strategies.png) + +## Deprecated strategies + +### gradualRolloutUserId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutuserid-deprecated-from-v4---use-gradual-rollout-instead} The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash value to a number between 1 and 100 with a simple modulo operator. @@ -93,7 +110,7 @@ Starting from v3.x all clients should use the 32-bit [MurmurHash3](https://en.wi - percentage - _The percentage (0-100) you want to enable the feature toggle for._ - groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._ -## gradualRolloutSessionId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutsessionid-deprecated-from-v4---use-gradual-rollout-instead} +### gradualRolloutSessionId (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutsessionid-deprecated-from-v4---use-gradual-rollout-instead} Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the session IDs. This makes it possible to target all users (not just logged-in users), guaranteeing that a user will get the same experience within a session. @@ -102,7 +119,7 @@ Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a - percentage - _The percentage (0-100) you want to enable the feature toggle for._ - groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._ -## gradualRolloutRandom (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutrandom-deprecated-from-v4---use-gradual-rollout-instead} +### gradualRolloutRandom (DEPRECATED from v4) - Use Gradual rollout instead {#gradualrolloutrandom-deprecated-from-v4---use-gradual-rollout-instead} The `gradualRolloutRandom` strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable a feature which is not visible to the user. It is also the strategy we use to sample metrics and error reports. From e43f1dd60f8fa8b759f5e950010afbfbd6ad03b2 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 13 Jan 2022 11:05:40 +0100 Subject: [PATCH 12/32] docs: delete control-rollout, redirect to activation strategies --- website/docs/user_guide/control-rollout.md | 48 ---------------------- website/docusaurus.config.js | 4 ++ 2 files changed, 4 insertions(+), 48 deletions(-) delete mode 100644 website/docs/user_guide/control-rollout.md diff --git a/website/docs/user_guide/control-rollout.md b/website/docs/user_guide/control-rollout.md deleted file mode 100644 index 3f667adf17..0000000000 --- a/website/docs/user_guide/control-rollout.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: control_rollout -title: Control rollout ---- - -It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. The next level of control comes when you are able to enable a feature for specific users or enable it for a small subset of users. - -In this guide you will learn how to control the roll-out (expose it to real users) of a new feature with the help of activation strategies. - -## Built in activation strategies {#built-in-activation-strategies} - -Unleash comes with a few common activation strategies. Some of them require the client to provide the unleash-context, which gives the necessary context for Unleash. - -The built-in activation strategies: - -- Standard -- UserIDs -- Gradual Rollout -- IPs -- Hostnames - -## The standard activation strategy {#the-standard-activation-strategy} - -When you create a new feature toggle you will get the standard activation strategy, if you donโ€™t configure any specific strategies. The standard activation strategy will always evaluate to true, given that the feature toggle is enabled. - -![A UI element describing the \"standard\" strategy. It says \"The standard strategy is strictly on / off for your entire userbase\".](/img/control_rollout_standard_strategy.png) - -## The UserIDs strategy {#the-userids-strategy} - -When we have deployed some new code to production it would be nice to enable the new feature for ourselves before we enable it to everyone else. To achieve this with Unleash, you can use the **UserIDs** activation strategy. This strategy allows you to specify a list of user IDs that you want to expose the new feature for. - -A userId is how you identify users in your system (email, UUID, etc) and is provided as part of the Unleash Context to the client SDK. - -![A UI element showing the user ID strategy. It has an active list of two user IDs: \"productlead@mycompany.com\" and \"me@mycompany.com\".](/img/control_rollout_userid_strategy.png) - -## Multiple activation strategies {#multiple-activation-strategies} - -In order to increase the exposure of the feature which is protected with the feature toggle you can configure multiple activation strategies on the same feature toggle. - -![A feature toggle with two active strategies: a user ID strategy and a gradual rollout strategy.](/img/control_rollout_multiple_strategies.png) - -In the example above we have to configure two activation strategies, **userWithId** and **flexibleRollout**. If one of them evaluates to true the feature toggle is considered enabled. In the example we have enabled the feature toggle for usersWithId (*productlead@mycompany.com* and *me@mycompany.com*) in addition to 75% of the traffic. - -## Summary {#summary} - -You use activation strategies to control who the feature toggle will be enabled for. You can configure multiple strategies for a feature toggle, and they are considered in an OR fashion, meaning if one of them evaluates to true the toggle will be enabled. - -If you need to limit the exposure (AND) you should look in to [strategy constraints](advanced/strategy-constraints.md), which is the building block for that. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 906d0dc2e1..cab7229147 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -151,6 +151,10 @@ module.exports = { to: '/integrations', from: '/integrations/integrations', }, + { + to: '/user_guide/activation_strategy', + from: '/user_guide/control_rollout', + }, ], createRedirects: function(toPath) { if ( From bf7231bdab0a107727fc48313619bae561533c24 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Thu, 13 Jan 2022 11:07:44 +0100 Subject: [PATCH 13/32] docs: group sdks by server/client --- website/sidebars.js | 68 ++++++++++++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 042dd5a53c..542aa1c0e5 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -88,43 +88,61 @@ module.exports = { ], }, { - 'Client SDKs': [ + 'Unleash SDKs': [ 'sdks/index', - 'sdks/java_sdk', - 'sdks/node_sdk', - 'sdks/dot_net_sdk', - 'sdks/go_sdk', - 'sdks/python_sdk', - 'sdks/ruby_sdk', - 'sdks/php_sdk', 'sdks/unleash-proxy', - 'sdks/android_proxy_sdk', - 'sdks/proxy-javascript', - 'sdks/proxy-react', - 'sdks/proxy-ios', { - label: 'Community SDKs', + type: 'category', + collapsible: false, + label: 'Server-side SDKs', + items: [ + 'sdks/go_sdk', + 'sdks/java_sdk', + 'sdks/node_sdk', + 'sdks/php_sdk', + 'sdks/python_sdk', + 'sdks/ruby_sdk', + { + type: 'link', + href: 'https://github.com/unleash/unleash-client-rust', + label: 'Rust SDK', + }, + 'sdks/dot_net_sdk', + ], + }, + { + type: 'category', + collapsible: false, + label: 'Client-side SDKs', + items: [ + 'sdks/android_proxy_sdk', + 'sdks/proxy-ios', + 'sdks/proxy-javascript', + 'sdks/proxy-react', + ], + }, + { type: 'link', + label: 'Community SDKs', href: '/sdks#community-sdks', }, ], 'Unleash concepts': [ 'user_guide/activation_strategy', - 'user_guide/control_rollout', - 'user_guide/projects', - 'user_guide/environments', - 'user_guide/unleash_context', - 'user_guide/rbac', - 'user_guide/technical_debt', - 'advanced/strategy_constraints', - 'advanced/custom_activation_strategy', - 'advanced/feature_toggle_types', - 'advanced/toggle_variants', - 'advanced/stickiness', 'advanced/archived_toggles', 'advanced/audit_log', - 'advanced/tags', + 'advanced/custom_activation_strategy', + 'user_guide/environments', + 'advanced/feature_toggle_types', + 'advanced/toggle_variants', + 'user_guide/projects', + 'user_guide/rbac', 'advanced/enterprise-authentication', + 'advanced/stickiness', + 'advanced/strategy_constraints', + 'advanced/tags', + 'user_guide/technical_debt', + 'user_guide/unleash_context', ], 'Deploy and manage Unleash': [ 'deploy/getting_started', From 286edba290657986093d57f82370a0a5042d0561 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 08:19:34 +0100 Subject: [PATCH 14/32] docs: place emoji before their following headings --- website/docs/user_guide/index.md | 2 +- website/sidebars.js | 70 +++++++++++++++++--------------- 2 files changed, 39 insertions(+), 33 deletions(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 8eae6928ea..0eb5af89ea 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -1,6 +1,6 @@ --- id: index -title: About the docs ๐Ÿ“š +title: ๐Ÿ“š About the docs slug: / sidebar_position: 1 --- diff --git a/website/sidebars.js b/website/sidebars.js index 542aa1c0e5..b8390bac7a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,16 +13,22 @@ module.exports = { documentation: [ 'user_guide/index', { - 'First steps ๐Ÿ‘ถ': [ + '๐Ÿ‘ถ First steps': [ 'user_guide/unleash_overview', 'user_guide/important-concepts', 'user_guide/quickstart', ], }, { - label: 'How-to guides ๐Ÿชœ', + label: '๐Ÿ›  How-to guides', type: 'category', collapsible: true, + link: { + type: 'generated-index', + title: 'How-to guides', + description: 'Step-by-step recipes for you to follow', + slug: '/how-to', + }, items: [ 'how-to/how-to-add-strategy-constraints', 'how-to/how-to-define-custom-context-fields', @@ -39,20 +45,28 @@ module.exports = { ], }, { - label: 'Reference documentation ๐Ÿ“œ', + label: '๐Ÿ“– Reference documentation', type: 'category', - collapsible: false, + collapsible: true, items: [ { - type: 'category', - link: { type: 'doc', id: 'addons/index' }, - items: [ - 'addons/webhook', - 'addons/slack', - 'addons/teams', - 'addons/datadog', + 'Unleash concepts': [ + 'user_guide/activation_strategy', + 'advanced/archived_toggles', + 'advanced/audit_log', + 'advanced/custom_activation_strategy', + 'user_guide/environments', + 'advanced/feature_toggle_types', + 'advanced/toggle_variants', + 'user_guide/projects', + 'user_guide/rbac', + 'advanced/enterprise-authentication', + 'advanced/stickiness', + 'advanced/strategy_constraints', + 'advanced/tags', + 'user_guide/technical_debt', + 'user_guide/unleash_context', ], - label: 'Addons', }, { type: 'category', @@ -93,7 +107,6 @@ module.exports = { 'sdks/unleash-proxy', { type: 'category', - collapsible: false, label: 'Server-side SDKs', items: [ 'sdks/go_sdk', @@ -112,7 +125,6 @@ module.exports = { }, { type: 'category', - collapsible: false, label: 'Client-side SDKs', items: [ 'sdks/android_proxy_sdk', @@ -127,23 +139,6 @@ module.exports = { href: '/sdks#community-sdks', }, ], - 'Unleash concepts': [ - 'user_guide/activation_strategy', - 'advanced/archived_toggles', - 'advanced/audit_log', - 'advanced/custom_activation_strategy', - 'user_guide/environments', - 'advanced/feature_toggle_types', - 'advanced/toggle_variants', - 'user_guide/projects', - 'user_guide/rbac', - 'advanced/enterprise-authentication', - 'advanced/stickiness', - 'advanced/strategy_constraints', - 'advanced/tags', - 'user_guide/technical_debt', - 'user_guide/unleash_context', - ], 'Deploy and manage Unleash': [ 'deploy/getting_started', 'deploy/configuring_unleash', @@ -156,6 +151,17 @@ module.exports = { 'deploy/import_export', ], }, + { + type: 'category', + link: { type: 'doc', id: 'addons/index' }, + items: [ + 'addons/webhook', + 'addons/slack', + 'addons/teams', + 'addons/datadog', + ], + label: 'Addons', + }, { type: 'category', label: 'Integrations', @@ -173,7 +179,7 @@ module.exports = { ], }, { - 'Topic guides ๐Ÿค“': ['topics/a-b-testing'], + '๐Ÿค“ Topic guides': ['topics/a-b-testing'], }, ], }; From 5e556bc87db9869632d2151861db673f3a080652 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 13:08:04 +0100 Subject: [PATCH 15/32] Rename all how-to guides to start with 'how to'. --- website/docs/advanced/api_access.md | 4 ++-- website/docs/advanced/sso-google.md | 2 +- website/docs/advanced/sso-open-id-connect.md | 2 +- website/docs/advanced/sso-saml-keycloak.md | 2 +- website/docs/advanced/sso-saml.md | 2 +- .../docs/user_guide/create-feature-toggle.md | 2 +- website/docs/user_guide/token.md | 2 +- website/docs/user_guide/user-management.md | 20 +++++++++---------- 8 files changed, 17 insertions(+), 19 deletions(-) diff --git a/website/docs/advanced/api_access.md b/website/docs/advanced/api_access.md index e841b7cae6..2d0d674a8c 100644 --- a/website/docs/advanced/api_access.md +++ b/website/docs/advanced/api_access.md @@ -1,13 +1,13 @@ --- id: api_access -title: API Access +title: How to use the Admin API --- It is possible to integrate directly with the Admin API. In this guide we will explain all the steps to set it up. ## Step 1: Create API token {#step-1-create-api-token} -Please refer to [Create token](../user_guide/api-token) on how to create an API token. You'll need a token with `Admin` level access for this to work. +Please refer to [_how to create API tokens_](../user_guide/api-token) on how to create an API token. You'll need a token with `Admin` level access for this to work. Please note that it may take up to 60 seconds for the new key to propagate to all Unleash instances due to eager caching. diff --git a/website/docs/advanced/sso-google.md b/website/docs/advanced/sso-google.md index 7e2584d768..909dc6d0cc 100644 --- a/website/docs/advanced/sso-google.md +++ b/website/docs/advanced/sso-google.md @@ -1,6 +1,6 @@ --- id: sso-google -title: SSO - Google (deprecated) +title: How to add SSO with Google (deprecated) --- > Single Sign-on via the Google Authenticator provider is deprecated. We recommend using [OpenId Connect](./sso-open-id-connect.md) instead. diff --git a/website/docs/advanced/sso-open-id-connect.md b/website/docs/advanced/sso-open-id-connect.md index a826d7d8c7..b2cd6a4ece 100644 --- a/website/docs/advanced/sso-open-id-connect.md +++ b/website/docs/advanced/sso-open-id-connect.md @@ -1,6 +1,6 @@ --- id: sso-open-id-connect -title: SSO - OpenId Connect +title: How to add SSO with OpenId Connect --- > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details. diff --git a/website/docs/advanced/sso-saml-keycloak.md b/website/docs/advanced/sso-saml-keycloak.md index 0f4e466046..1d55381176 100644 --- a/website/docs/advanced/sso-saml-keycloak.md +++ b/website/docs/advanced/sso-saml-keycloak.md @@ -1,6 +1,6 @@ --- id: sso-saml-keycloak -title: SSO - SAML 2.0 Keycloak +title: How to add SSO with SAML 2.0 Keycloak --- > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details. diff --git a/website/docs/advanced/sso-saml.md b/website/docs/advanced/sso-saml.md index 821ed80a38..663bbcb1d6 100644 --- a/website/docs/advanced/sso-saml.md +++ b/website/docs/advanced/sso-saml.md @@ -1,6 +1,6 @@ --- id: sso-saml -title: SSO - SAML 2.0 Okta +title: How to add SSO with SAML 2.0 Okta --- > The **Single-Sign-On capability** is only available for customers on the Enterprise subscription. Check out the [Unleash plans](https://www.getunleash.io/plans) for details. diff --git a/website/docs/user_guide/create-feature-toggle.md b/website/docs/user_guide/create-feature-toggle.md index 5d46e3b808..119c851919 100644 --- a/website/docs/user_guide/create-feature-toggle.md +++ b/website/docs/user_guide/create-feature-toggle.md @@ -1,6 +1,6 @@ --- id: create_feature_toggle -title: Create a feature toggle +title: How to create a feature toggle --- In this guide you will learn how to create your first feature toggle using Unleash. diff --git a/website/docs/user_guide/token.md b/website/docs/user_guide/token.md index b6ab8586d1..29a24d1f5d 100644 --- a/website/docs/user_guide/token.md +++ b/website/docs/user_guide/token.md @@ -1,6 +1,6 @@ --- id: api-token -title: API Tokens +title: How to create API Tokens --- In order to connect to Unleash clients will need an API token to grant access. A client SDK will need to token with "client privileges", which allows them to fetch feature toggle configuration and post usage metrics back. diff --git a/website/docs/user_guide/user-management.md b/website/docs/user_guide/user-management.md index ef42be043a..04cd0686d1 100644 --- a/website/docs/user_guide/user-management.md +++ b/website/docs/user_guide/user-management.md @@ -1,23 +1,21 @@ --- id: user-management -title: User Management +title: How to add new users to your Unleash instance --- > This feature was introduced in Unleash v4 for Unleash Open-Source. -You can manage users with access to Unleash in the `Admin > Users`. +You can add new users to Unleash in `Admin > Users`. -From the top-line menu โ€“ click on the โ€œSettings Wheelโ€ then click on โ€œUsersโ€. -![Add user button](/img/user_admin_list_button.png) +1. From the top-line menu โ€“ click on the โ€œSettings Wheelโ€ then click on โ€œUsersโ€. + ![A visual representation of the current step: the Unleash Admin UI with the steps highlighted.](/img/user_admin_list_button.png) +2. To add a new user to your Unleash instance simply click the "Add user" button: + ![The Unleash users page with the 'add new user' button being pointed to.](/img/user_admin-add-user.jpg) +3. Fill out the required fields about the user in the modal. You need to choose which role the new user should have on the "root level". E.g. giving the user an Editor role will allow the user to create a new project. -To add a new user to your Unleash instance simply click the "Add user" button: -![Add user button](/img/user_admin-add-user.jpg) + ![A form titled "Add team member". It has the fields "full name", "email", and "role". The role field is a radio button set with roles called "admin", "editor", and "viewer".](/img/user_admin_add_user_modal.png) -Fill out the required fields about the user in the modal. You need to choose which role the new user should have on the "root level". E.g. giving the user an Editor role will allow the user to create a new project. - -![Add user button](/img/user_admin_add_user_modal.png) - -If you have configured an email server the user will receive the invite link in her inbox, otherwise you should share the magic invite link to Unleash presented in the confirmation dialogue. + If you have configured an email server the user will receive the invite link in her inbox, otherwise you should share the magic invite link to Unleash presented in the confirmation dialogue. From a13a4632551d7a4c5c09ca0d6ad7bdf3df3d08be Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 13:18:53 +0100 Subject: [PATCH 16/32] =?UTF-8?q?docs:=20change=20topic=20emoji=20from=20?= =?UTF-8?q?=F0=9F=A4=93=20->=20=F0=9F=A7=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- website/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/sidebars.js b/website/sidebars.js index b8390bac7a..11db850b73 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -179,7 +179,7 @@ module.exports = { ], }, { - '๐Ÿค“ Topic guides': ['topics/a-b-testing'], + '๐Ÿง  Topic guides': ['topics/a-b-testing'], }, ], }; From de412081640995f3c3cbac807510bca2d61b4809 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 13:19:13 +0100 Subject: [PATCH 17/32] docs: create categories and group how-to guides. This probably needs more discussion etc, but it's a good start, I think. --- website/sidebars.js | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 11db850b73..670b102152 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -30,18 +30,25 @@ module.exports = { slug: '/how-to', }, items: [ - 'how-to/how-to-add-strategy-constraints', - 'how-to/how-to-define-custom-context-fields', - 'how-to/how-to-use-custom-strategies', - - 'advanced/sso-open-id-connect', - 'advanced/sso-saml', - 'advanced/sso-saml-keycloak', - 'advanced/sso-google', - 'advanced/api_access', - 'user_guide/api-token', - 'user_guide/user-management', - 'user_guide/create_feature_toggle', + { + API: ['advanced/api_access', 'user_guide/api-token'], + 'Feature toggles, strategies, and related': [ + 'how-to/how-to-add-strategy-constraints', + 'how-to/how-to-define-custom-context-fields', + 'how-to/how-to-use-custom-strategies', + 'user_guide/create_feature_toggle', + ], + 'Users and permissions': [ + 'how-to/how-to-create-and-assign-custom-project-roles', + 'user_guide/user-management', + ], + SSO: [ + 'advanced/sso-open-id-connect', + 'advanced/sso-saml', + 'advanced/sso-saml-keycloak', + 'advanced/sso-google', + ], + }, ], }, { From 43604df3802d8fa85da503ea5827ef9b5999e739 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 13:24:05 +0100 Subject: [PATCH 18/32] docs: sort all sidebar items --- website/sidebars.js | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 670b102152..744b314880 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -31,22 +31,22 @@ module.exports = { }, items: [ { - API: ['advanced/api_access', 'user_guide/api-token'], - 'Feature toggles, strategies, and related': [ + API: ['user_guide/api-token', 'advanced/api_access'], + 'Feature toggles, strategies, context': [ 'how-to/how-to-add-strategy-constraints', + 'user_guide/create_feature_toggle', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', - 'user_guide/create_feature_toggle', ], 'Users and permissions': [ - 'how-to/how-to-create-and-assign-custom-project-roles', 'user_guide/user-management', + 'how-to/how-to-create-and-assign-custom-project-roles', ], SSO: [ + 'advanced/sso-google', 'advanced/sso-open-id-connect', 'advanced/sso-saml', 'advanced/sso-saml-keycloak', - 'advanced/sso-google', ], }, ], @@ -149,23 +149,23 @@ module.exports = { 'Deploy and manage Unleash': [ 'deploy/getting_started', 'deploy/configuring_unleash', - 'deploy/securing_unleash', - 'deploy/email', - 'deploy/google_auth', 'deploy/database-setup', 'deploy/database_backup', - 'deploy/migration_guide', + 'deploy/email', + 'deploy/google_auth', 'deploy/import_export', + 'deploy/migration_guide', + 'deploy/securing_unleash', ], }, { type: 'category', link: { type: 'doc', id: 'addons/index' }, items: [ - 'addons/webhook', + 'addons/datadog', 'addons/slack', 'addons/teams', - 'addons/datadog', + 'addons/webhook', ], label: 'Addons', }, From 775da4787b847261d588e5d672302ec4d9be8796 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 13:40:56 +0100 Subject: [PATCH 19/32] docs: remove links to deployment, integrations, and api. --- website/docusaurus.config.js | 3 --- 1 file changed, 3 deletions(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index cab7229147..d8c7d9ca38 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -30,9 +30,6 @@ module.exports = { label: 'Documentation', activeBaseRegex: '(user_guide|sdks|addons|advanced)', }, - { to: 'deploy/getting_started', label: 'Deploy and manage' }, - { to: 'integrations', label: 'Integrations' }, - { to: '/api', label: 'API' }, { href: 'https://www.getunleash.io/plans', label: 'Unleash Enterprise', From 6d43b93be2264b0ab097b9b6c15a9945ce7e1f85 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 14 Jan 2022 14:20:28 +0100 Subject: [PATCH 20/32] docs(chore): fix broken links to control_rollout --- website/docs/sdks/java.md | 2 +- website/docs/sdks/php.md | 2 +- website/docs/user_guide/create-feature-toggle.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/sdks/java.md b/website/docs/sdks/java.md index 978a92670a..8968113756 100644 --- a/website/docs/sdks/java.md +++ b/website/docs/sdks/java.md @@ -57,7 +57,7 @@ Read more about the [Unleash architecture](https://www.unleash-hosted.com/articl ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context} -It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK. +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/activation-strategies.md), which are implemented in the client SDK. The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. diff --git a/website/docs/sdks/php.md b/website/docs/sdks/php.md index 54f4d45682..cf5d2572f2 100644 --- a/website/docs/sdks/php.md +++ b/website/docs/sdks/php.md @@ -56,7 +56,7 @@ Read more about the [Unleash architecture](https://www.unleash-hosted.com/articl ## Step 4: Provide Unleash Context {#step-4-provide-unleash-context} -It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/control_rollout), which are implemented in the client SDK. +It is the client SDK that computes whether a feature toggle should be considered enabled or disabled for specific use request. This is the job of the [activation strategies](../user_guide/activation-strategies.md), which are implemented in the client SDK. The activation strategies is an implementation of rules based on data, which you provide as part of the Unleash Context. diff --git a/website/docs/user_guide/create-feature-toggle.md b/website/docs/user_guide/create-feature-toggle.md index 119c851919..ffcf4e560e 100644 --- a/website/docs/user_guide/create-feature-toggle.md +++ b/website/docs/user_guide/create-feature-toggle.md @@ -32,7 +32,7 @@ The toggle is now created and ready to be used. The toggle does not have any met ## Step 4: Enable the feature toggle only for your boss! {#step-4-enable-the-feature-toggle-only-for-your-boss} -The next step is to change the activation strategy to only target your boss. You can use the โ€œuserWithIdโ€-strategy for that. Using the configuration shown below will only enable the feature toggle for โ€œboss@company.comโ€ and โ€œme@company.comโ€. Thus, you can safely test your feature in production, without exposing it to your users. In [control roll-out](./control_rollout) with strategies we will go in to greater details on how to use activation strategies to gradually expose new features to your users. +The next step is to change the activation strategy to only target your boss. You can use the โ€œuserIDsโ€-strategy for that. Using the configuration shown below will only enable the feature toggle for โ€œboss@company.comโ€ and โ€œme@company.comโ€. Thus, you can safely test your feature in production, without exposing it to your users. ![Create a feature toggle](/img/create_feature_toggle_userIds.png) From 3dec1ee7b213b55f65345acca8b05314cf8142b9 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 21 Jan 2022 07:39:10 +0100 Subject: [PATCH 21/32] docs: remove emoji, add placeholder links to landing page. --- website/docs/user_guide/index.md | 22 ++++++++++++++++++---- website/sidebars.js | 8 ++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 0eb5af89ea..65f10fc391 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -1,6 +1,6 @@ --- id: index -title: ๐Ÿ“š About the docs +title: About the docs slug: / sidebar_position: 1 --- @@ -27,14 +27,28 @@ New to Unleash? Not sure where to get started? The tutorials guide you through t Our how-to guides show you how to perform a number of common tasks that you'll want to do. Think of them as recipes. They are more advanced than the tutorials and assume you have some working knowledge of Unleash. -### Topic guides - -Topic guides discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts. +The guides are organized into the following topics: +- API [/how-to/api] +- Feature toggles, strategies, context [/how-to/general] +- Users and permissions [/how-to/permissions] +- SSO [/how-to/single-sign-on] ### Reference documentation The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts. +The reference docs are organized into the following topics: +- Unleash concepts [/reference/concepts] +- APIs [/reference/api] +- Unleash SDKs [/reference/sdk] +- Deploy and manage unleash [/reference/deployment] +- Addons [/reference/addons] +- Integrations [/reference/integrations] + +### Topic guides + +Topic guides discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts. + ## Other resources and communities ๐Ÿ’ป The core of Unleash is all open source and [hosted on GitHub](https://www.heroku.com/deploy/?template=https://github.com/Unleash/unleash "Unleash on GitHub"). diff --git a/website/sidebars.js b/website/sidebars.js index 744b314880..b8f694716a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,14 +13,14 @@ module.exports = { documentation: [ 'user_guide/index', { - '๐Ÿ‘ถ First steps': [ + 'First steps': [ 'user_guide/unleash_overview', 'user_guide/important-concepts', 'user_guide/quickstart', ], }, { - label: '๐Ÿ›  How-to guides', + label: 'How-to guides', type: 'category', collapsible: true, link: { @@ -52,7 +52,7 @@ module.exports = { ], }, { - label: '๐Ÿ“– Reference documentation', + label: 'Reference documentation', type: 'category', collapsible: true, items: [ @@ -186,7 +186,7 @@ module.exports = { ], }, { - '๐Ÿง  Topic guides': ['topics/a-b-testing'], + 'Topic guides': ['topics/a-b-testing'], }, ], }; From ea0ff8f991cbea873ef0d41009e7ddb51ff8a068 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Fri, 21 Jan 2022 12:15:14 +0100 Subject: [PATCH 22/32] docs: Potential fix to SSO guide ordering (with deprecated guides) --- website/docs/advanced/sso-google.md | 2 +- website/sidebars.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/advanced/sso-google.md b/website/docs/advanced/sso-google.md index 909dc6d0cc..4cfcf26931 100644 --- a/website/docs/advanced/sso-google.md +++ b/website/docs/advanced/sso-google.md @@ -1,6 +1,6 @@ --- id: sso-google -title: How to add SSO with Google (deprecated) +title: "[Deprecated] How to add SSO with Google" --- > Single Sign-on via the Google Authenticator provider is deprecated. We recommend using [OpenId Connect](./sso-open-id-connect.md) instead. diff --git a/website/sidebars.js b/website/sidebars.js index b8f694716a..fd84cf266c 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -43,10 +43,10 @@ module.exports = { 'how-to/how-to-create-and-assign-custom-project-roles', ], SSO: [ - 'advanced/sso-google', 'advanced/sso-open-id-connect', 'advanced/sso-saml', 'advanced/sso-saml-keycloak', + 'advanced/sso-google', ], }, ], From 738643eb242ce37e333b03ed397b843be6b999d3 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 13:41:29 +0100 Subject: [PATCH 23/32] docs: Add landing pages for all first and second-level categories. --- website/sidebars.js | 119 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 11 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index fd84cf266c..792ff6a228 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -13,7 +13,15 @@ module.exports = { documentation: [ 'user_guide/index', { - 'First steps': [ + label: 'First steps and tutorials', + type: 'category', + link: { + type: 'generated-index', + title: 'First steps', + description: 'Learn how and where to get started with Unleash.', + slug: '/tutorials', + }, + items: [ 'user_guide/unleash_overview', 'user_guide/important-concepts', 'user_guide/quickstart', @@ -26,38 +34,94 @@ module.exports = { link: { type: 'generated-index', title: 'How-to guides', - description: 'Step-by-step recipes for you to follow', + description: 'Step-by-step recipes for you to follow.', slug: '/how-to', }, items: [ { - API: ['user_guide/api-token', 'advanced/api_access'], - 'Feature toggles, strategies, context': [ + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: Unleash API', + description: 'Learn how to work with the Unleash API', + slug: '/how-to/api', + }, + label: 'API', + items: ['user_guide/api-token', 'advanced/api_access'], + }, + { + label: 'Feature toggles, strategies, context', + items: [ 'how-to/how-to-add-strategy-constraints', 'user_guide/create_feature_toggle', 'how-to/how-to-define-custom-context-fields', 'how-to/how-to-use-custom-strategies', ], - 'Users and permissions': [ + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: general Unleash tasks', + description: + 'Guides for how to perform general Unleash tasks.', + slug: '/how-to/misc', + }, + }, + { + label: 'Users and permissions', + items: [ 'user_guide/user-management', 'how-to/how-to-create-and-assign-custom-project-roles', ], - SSO: [ + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: users and permissions', + description: 'Users and permission how-to guides.', + slug: '/how-to/users-and-permissions', + }, + }, + { + label: 'Single Sign-On (SSO)', + items: [ 'advanced/sso-open-id-connect', 'advanced/sso-saml', 'advanced/sso-saml-keycloak', 'advanced/sso-google', ], + type: 'category', + link: { + type: 'generated-index', + title: 'How-to: Single Sign-On', + description: 'Single Sign-On how-to guides.', + slug: '/how-to/sso', + }, }, + , ], }, { label: 'Reference documentation', type: 'category', + link: { + type: 'generated-index', + title: 'Reference documentation', + description: + 'Technical reference documentation relating to Unleash, including APIs, SDKs, Unleash concepts and deployment.', + slug: '/reference', + }, collapsible: true, items: [ { - 'Unleash concepts': [ + type: 'category', + link: { + type: 'generated-index', + title: 'Unleash concepts', + description: + 'Documents describing the inner parts of Unleash.', + slug: '/reference/concepts', + }, + label: 'Unleash concepts', + items: [ 'user_guide/activation_strategy', 'advanced/archived_toggles', 'advanced/audit_log', @@ -94,6 +158,17 @@ module.exports = { 'api/admin/state', 'api/admin/strategies', 'api/admin/user-admin', + { + type: 'category', + label: 'subcat', + link: { + type: 'generated-index', + title: 'Subcat', + description: 'Lorem ipsum', + slug: '/api/subcat', + }, + items: ['api/admin/user-admin'], + }, ], 'Client API': [ 'api/client/features', @@ -109,8 +184,10 @@ module.exports = { ], }, { - 'Unleash SDKs': [ - 'sdks/index', + type: 'category', + label: 'Unleash SDKs', + link: { type: 'doc', id: 'sdks/index' }, + items: [ 'sdks/unleash-proxy', { type: 'category', @@ -146,7 +223,18 @@ module.exports = { href: '/sdks#community-sdks', }, ], - 'Deploy and manage Unleash': [ + }, + { + type: 'category', + link: { + type: 'generated-index', + title: 'Deployment and management of Unleash', + description: + 'All you need to learn how to deploy and manage your own Unleash instance.', + slug: '/deploy', + }, + label: 'Deploy and manage Unleash', + items: [ 'deploy/getting_started', 'deploy/configuring_unleash', 'deploy/database-setup', @@ -186,7 +274,16 @@ module.exports = { ], }, { - 'Topic guides': ['topics/a-b-testing'], + label: 'Topic guides', + type: 'category', + link: { + type: 'generated-index', + title: 'Topic guides', + description: + 'Discussions, explanations, and explorations regarding topics related to Unleash.', + slug: '/topics', + }, + items: ['topics/a-b-testing'], }, ], }; From 100e13695171485eb3dfa264f3e7c628d317263f Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 14:34:48 +0100 Subject: [PATCH 24/32] docs: flesh out integrations category page. --- website/docs/integrations/integrations.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/website/docs/integrations/integrations.md b/website/docs/integrations/integrations.md index a79f09c51f..888a227220 100644 --- a/website/docs/integrations/integrations.md +++ b/website/docs/integrations/integrations.md @@ -2,8 +2,21 @@ id: integrations title: External Integrations and plugins --- +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; -Available integrations with Unleash + +Unleash can also integrate with other systems in different ways. + +## Official integrations + +Unleash provides these official integrations: + + + +## Community-contributed integrations: + +Our wonderful community has also created the following integrations: - [Vue Unleash plugin](https://github.com/crishellco/vue-unleash) - [Quarkus](https://github.com/quarkiverse/quarkus-unleash) From f944a40d78247822108cc47b66f2182be5ce398e Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 14:39:02 +0100 Subject: [PATCH 25/32] docs: Extend docs landing page; add more links, structure, etc. --- website/docs/user_guide/index.md | 37 +++++++++++++++++++------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 65f10fc391..8502265083 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -17,37 +17,44 @@ Have questions that you can't find the answer to in these docs? You can always t ## Documentation structure -Our documentation is split into four parts, using the [Diataxis documentation framework](https://diataxis.fr/): documentation, how-to guides, topic guides, and reference documentation. +Our documentation is split into four parts, using the [Diataxis documentation framework](https://diataxis.fr/): +- [tutorials and introductory material](#tutorials) +- [how-to guides](#how-to-guides) +- [topic guides](#topic-guides) +- [reference documentation](#reference-documentation) -### Tutorials +### Tutorials and introductory material {#tutorials} -New to Unleash? Not sure where to get started? The tutorials guide you through taking your first steps with Unleash. +New to Unleash? Not sure where to get started? The tutorials guide you through your first steps with Unleash: +- [Unleash introductory overview](unleash_overview.md) +- [Important Unleash concepts](important-concepts.md) +- [Quickstart guides](quickstart.md) ### How-to guides Our how-to guides show you how to perform a number of common tasks that you'll want to do. Think of them as recipes. They are more advanced than the tutorials and assume you have some working knowledge of Unleash. -The guides are organized into the following topics: -- API [/how-to/api] -- Feature toggles, strategies, context [/how-to/general] -- Users and permissions [/how-to/permissions] -- SSO [/how-to/single-sign-on] +The guides are organized into the following categories: +- [API how-tos](/how-to/api) +- [Feature toggles, strategies, context, and general how-tos](/how-to/misc) +- [Users and permissions how-tos](/how-to/users-and-permissions) +- [Single Sign-On (SSO) how-tos](/how-to/sso) ### Reference documentation The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts. The reference docs are organized into the following topics: -- Unleash concepts [/reference/concepts] -- APIs [/reference/api] -- Unleash SDKs [/reference/sdk] -- Deploy and manage unleash [/reference/deployment] -- Addons [/reference/addons] -- Integrations [/reference/integrations] +- [Unleash concepts](/reference/concepts) +- [API documentation](/api) +- [Unleash SDKs](/sdks) +- [Deploy and manage unleash](/deploy) +- [Addons](/addons) +- [Integrations](/integrations) ### Topic guides -Topic guides discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts. +[The topic guides](/topics) discuss high-level concepts related to Unleash and provide extra background information and explanations around these concepts. ## Other resources and communities From fe17c4f06222d10df5c98565bbe3317620a4046c Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 16:10:14 +0100 Subject: [PATCH 26/32] docs: add purple squares to the top level categories. --- website/src/css/custom.css | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/website/src/css/custom.css b/website/src/css/custom.css index a0ca34ea6b..6a59a0a9b0 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -7,6 +7,7 @@ /* You can override the default Infima variables here. */ :root { + --color-unleash-purple: #635DC5; --ifm-color-primary: #39535b; --ifm-color-primary-dark: #334b52; --ifm-color-primary-darker: #30474d; @@ -16,7 +17,7 @@ --ifm-color-primary-lightest: #4a6c76; --ifm-code-font-size: 90%; --ifm-font-size-base: 15px; - --ifm-link-color: #635DC5; + --ifm-link-color: var(--color-unleash-purple); --navbar-link-color: #122d33; } @@ -28,6 +29,17 @@ footer { font-size: 2.5rem !important; } +li.theme-doc-sidebar-item-category-level-1 > div::before { + width: .8em; + height: .8em; + content: " "; + position: absolute; + background-color: var(--color-unleash-purple); + left: -.1em; + top: calc(50% - .4em); + border-radius: 2px; +} + .docusaurus-highlight-code-line { background-color: rgb(72, 77, 91); display: block; From 1b48bc0a9e4eebaaf55f66edab9fb86a333f1642 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 16:13:46 +0100 Subject: [PATCH 27/32] docs: sidebar markers // use vertical pipes instead. --- website/src/css/custom.css | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 6a59a0a9b0..b7f76ecf0a 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -30,14 +30,13 @@ footer { } li.theme-doc-sidebar-item-category-level-1 > div::before { - width: .8em; - height: .8em; + width: .3em; + height: 100%; content: " "; - position: absolute; background-color: var(--color-unleash-purple); - left: -.1em; - top: calc(50% - .4em); border-radius: 2px; + position: absolute; + /* left: -.3em; */ } .docusaurus-highlight-code-line { From a78f4bd4c46d03ecaec98a7a15636ef0cb0cf3ee Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Mon, 24 Jan 2022 16:16:31 +0100 Subject: [PATCH 28/32] fix: remove unused style --- website/src/css/custom.css | 1 - 1 file changed, 1 deletion(-) diff --git a/website/src/css/custom.css b/website/src/css/custom.css index b7f76ecf0a..348329fdde 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -36,7 +36,6 @@ li.theme-doc-sidebar-item-category-level-1 > div::before { background-color: var(--color-unleash-purple); border-radius: 2px; position: absolute; - /* left: -.3em; */ } .docusaurus-highlight-code-line { From f62a65a23a655e7e78a562eaf193e4057dbc55bb Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Tue, 25 Jan 2022 12:25:08 +0100 Subject: [PATCH 29/32] docs: order the docs structure overview the same as the actual doc. --- website/docs/user_guide/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index 8502265083..c9d6a8857b 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -20,8 +20,8 @@ Have questions that you can't find the answer to in these docs? You can always t Our documentation is split into four parts, using the [Diataxis documentation framework](https://diataxis.fr/): - [tutorials and introductory material](#tutorials) - [how-to guides](#how-to-guides) -- [topic guides](#topic-guides) - [reference documentation](#reference-documentation) +- [topic guides](#topic-guides) ### Tutorials and introductory material {#tutorials} From ee55f6a9fb25978ba9f0ccb24fd2cd3b162bd534 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 26 Jan 2022 11:51:35 +0100 Subject: [PATCH 30/32] docs: make top-level categories open by default, re-order references --- website/docs/user_guide/index.md | 10 ++-- website/sidebars.js | 78 ++++++++++++++++---------------- 2 files changed, 45 insertions(+), 43 deletions(-) diff --git a/website/docs/user_guide/index.md b/website/docs/user_guide/index.md index c9d6a8857b..5e3c3fd069 100644 --- a/website/docs/user_guide/index.md +++ b/website/docs/user_guide/index.md @@ -45,12 +45,12 @@ The guides are organized into the following categories: The reference docs contain technical reference for Unleash and the API. Go here to find out how Unleash works and what configuration options are available. They're like an Unleash encyclopedia and assume you have a grip on key Unleash concepts. The reference docs are organized into the following topics: -- [Unleash concepts](/reference/concepts) -- [API documentation](/api) -- [Unleash SDKs](/sdks) -- [Deploy and manage unleash](/deploy) - [Addons](/addons) -- [Integrations](/integrations) +- [API documentation](/api) +- [Unleash Client SDKs](/sdks) +- [Deployment and management of Unleash](/deploy) +- [Integrations with other systems](/integrations) +- [Unleash concepts](/reference/concepts) ### Topic guides diff --git a/website/sidebars.js b/website/sidebars.js index 792ff6a228..05d05c53fd 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -15,6 +15,7 @@ module.exports = { { label: 'First steps and tutorials', type: 'category', + collapsed: false, link: { type: 'generated-index', title: 'First steps', @@ -29,8 +30,8 @@ module.exports = { }, { label: 'How-to guides', + collapsed: false, type: 'category', - collapsible: true, link: { type: 'generated-index', title: 'How-to guides', @@ -101,6 +102,7 @@ module.exports = { }, { label: 'Reference documentation', + collapsed: false, type: 'category', link: { type: 'generated-index', @@ -109,35 +111,17 @@ module.exports = { 'Technical reference documentation relating to Unleash, including APIs, SDKs, Unleash concepts and deployment.', slug: '/reference', }, - collapsible: true, items: [ { type: 'category', - link: { - type: 'generated-index', - title: 'Unleash concepts', - description: - 'Documents describing the inner parts of Unleash.', - slug: '/reference/concepts', - }, - label: 'Unleash concepts', + link: { type: 'doc', id: 'addons/index' }, items: [ - 'user_guide/activation_strategy', - 'advanced/archived_toggles', - 'advanced/audit_log', - 'advanced/custom_activation_strategy', - 'user_guide/environments', - 'advanced/feature_toggle_types', - 'advanced/toggle_variants', - 'user_guide/projects', - 'user_guide/rbac', - 'advanced/enterprise-authentication', - 'advanced/stickiness', - 'advanced/strategy_constraints', - 'advanced/tags', - 'user_guide/technical_debt', - 'user_guide/unleash_context', + 'addons/datadog', + 'addons/slack', + 'addons/teams', + 'addons/webhook', ], + label: 'Addons', }, { type: 'category', @@ -185,10 +169,9 @@ module.exports = { }, { type: 'category', - label: 'Unleash SDKs', + label: 'Client SDKs', link: { type: 'doc', id: 'sdks/index' }, items: [ - 'sdks/unleash-proxy', { type: 'category', label: 'Server-side SDKs', @@ -246,17 +229,6 @@ module.exports = { 'deploy/securing_unleash', ], }, - { - type: 'category', - link: { type: 'doc', id: 'addons/index' }, - items: [ - 'addons/datadog', - 'addons/slack', - 'addons/teams', - 'addons/webhook', - ], - label: 'Addons', - }, { type: 'category', label: 'Integrations', @@ -271,10 +243,40 @@ module.exports = { , ], }, + { + type: 'category', + link: { + type: 'generated-index', + title: 'Unleash concepts', + description: + 'Documents describing the inner parts of Unleash.', + slug: '/reference/concepts', + }, + label: 'Unleash concepts', + items: [ + 'user_guide/activation_strategy', + 'advanced/archived_toggles', + 'advanced/audit_log', + 'advanced/custom_activation_strategy', + 'user_guide/environments', + 'advanced/feature_toggle_types', + 'advanced/toggle_variants', + 'user_guide/projects', + 'user_guide/rbac', + 'advanced/enterprise-authentication', + 'advanced/stickiness', + 'advanced/strategy_constraints', + 'advanced/tags', + 'user_guide/technical_debt', + 'user_guide/unleash_context', + 'sdks/unleash-proxy', + ], + }, ], }, { label: 'Topic guides', + collapsed: false, type: 'category', link: { type: 'generated-index', From e697e146d659001728db994a8e0175fab9e179a0 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 26 Jan 2022 11:57:52 +0100 Subject: [PATCH 31/32] chore(format): run prettier on the custom css stylesheet --- website/src/css/custom.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 348329fdde..c00de0f93b 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -7,7 +7,7 @@ /* You can override the default Infima variables here. */ :root { - --color-unleash-purple: #635DC5; + --color-unleash-purple: #635dc5; --ifm-color-primary: #39535b; --ifm-color-primary-dark: #334b52; --ifm-color-primary-darker: #30474d; @@ -30,9 +30,9 @@ footer { } li.theme-doc-sidebar-item-category-level-1 > div::before { - width: .3em; + width: 0.3em; height: 100%; - content: " "; + content: ' '; background-color: var(--color-unleash-purple); border-radius: 2px; position: absolute; From bb37141899707ac3f137d4d5845c4cd8a3cd2bfa Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 26 Jan 2022 12:22:03 +0100 Subject: [PATCH 32/32] docs: Tweak github links (labels, text) --- website/docusaurus.config.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index d8c7d9ca38..c348e1f128 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -39,7 +39,7 @@ module.exports = { href: 'https://github.com/Unleash/unleash', position: 'right', className: 'header-github-link', - 'aria-label': 'GitHub repository', + 'aria-label': 'Unleash GitHub repository', }, ], }, @@ -57,7 +57,7 @@ module.exports = { to: '/', }, { - label: 'Open-Source', + label: 'Unleash on GitHub', href: 'https://github.com/Unleash/unleash', }, {