mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-22 19:07:54 +01:00
docs: Use Go readme (#2816)
# PR 1: add remote content plugin and rust readme ## What This PR does a few connected things: 1. It adds the ["docusaurus-plugin-remote-content" package](https://github.com/rdilweb/docusaurus-plugin-remote-content). 2. It adds configuration to make it work with Readmes found on GitHub. 3. It adds the Rust SDK's readme (replacing the link we used to have) as a proof of concept on how to do it. ## Why With documentation split between GitHub readmes and the official docs, it's hard to keep everything up to date and in sync. It's also quite confusing that some information is only available in some places, but not in others. We've talked about auto-including readmes from GitHub for a while, so here's a proof of concept (finally) 🥳 The intention is to get this merged and then to migrate the other SDK docs one by one, ensuring that everything in the documentation is also in the readme (so that no info is lost). ## Discussion points ### Generation directory The current generation method generates the files into `/reference/sdks/<sdk name>`. I think this works for now, but it means it adds auto-generated files into a directory that you can't ignore (at least not yet). We could instead generate them into `/generated/sdks` and update the slugs so that they still match the expected pattern. However, this would make the sidebar a little harder to work with (for now). That said, there may be ways around it. It's worth exploring. ### Generation method By default, this plugin will generate files whenever you build. That (probably) means that you need an internet connection _and_ that you'll end up with a bunch of untracked files. An option is to only generate the files "manually" and commit them to the repo. That would allow you to build the project without an internet connection and would also remove the need for ignoring the files. We could automate the generation if we wanted to. ## Preview / Screenies Visit [/reference/sdks/rust](https://unleash-docs-git-docs-include-sdk-readmes-unleash-team.vercel.app/reference/sdks/rust) in the preview to see what it looks like live.  # PR 2: add go readme This PR changes the docs generation to use the Go SDK's GitHub readme for the SDK docs instead of a separate document. ## What The changes in this PR are: - Delete the existing Go SDK documentation. All the content in this guide already exists in the Go readme. - Add the Go SDK to the list of auto-generated readme docs - Move the readme-related code into a separate module, `readme-fns.js` (I'm not bullish about the file name: we can change it if you have suggestions) - Add a note to the top of all generated readmes saying you'll need an API url and an API token. The note also links you to the relevant reference and how-to docs. ## Why Having two different bits of documentation for the same SDK is troublesome. By only having the data in one place, we can avoid it going out of sync and getting stale.
This commit is contained in:
Thomas Heartman
GitHub
parent
674e36b40b
commit
7cff6336c1
@ -1,83 +0,0 @@
|
||||
---
|
||||
title: GO SDK
|
||||
---
|
||||
|
||||
> You will need your `API URL` and your `API token` in order to connect the Client SDK to you Unleash instance. You can find this information in the “Admin” section Unleash management UI. [Read more](../../how-to/how-to-create-api-tokens.mdx)
|
||||
|
||||
### 1. Install unleash-client-go {#1-install-unleash-client-go}
|
||||
|
||||
To install the latest version of the client use:
|
||||
|
||||
```bash
|
||||
go get github.com/Unleash/unleash-client-go/v3
|
||||
```
|
||||
|
||||
If you are still using Unleash Server v2.x.x, then you should use:
|
||||
|
||||
```bash
|
||||
go get github.com/Unleash/unleash-client-go
|
||||
```
|
||||
|
||||
### 2. Initialize unleash {#2-initialize-unleash}
|
||||
|
||||
The easiest way to get started with Unleash is to initialize it early in your application code:
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/Unleash/unleash-client-go/v3"
|
||||
)
|
||||
|
||||
func init() {
|
||||
unleash.Initialize(
|
||||
unleash.WithListener(&unleash.DebugListener{}),
|
||||
unleash.WithAppName("my-application"),
|
||||
unleash.WithUrl("https://unleash.example.com/api/"),
|
||||
unleash.WithCustomHeaders(http.Header{"Authorization": {"<API token>"}}),
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Use unleash {#3-use-unleash}
|
||||
|
||||
After you have initialized the unleash-client you can easily check if a feature toggle is enabled or not.
|
||||
|
||||
```go
|
||||
unleash.IsEnabled("app.ToggleX")
|
||||
```
|
||||
|
||||
### 4. Stop unleash {#4-stop-unleash}
|
||||
|
||||
To shut down the client (turn off the polling) you can simply call the destroy-method. This is typically not required.
|
||||
|
||||
unleash.Close()
|
||||
|
||||
### Built-in activation strategies {#built-in-activation-strategies}
|
||||
|
||||
The Go client comes with implementations for the built-in activation strategies provided by unleash.
|
||||
|
||||
- DefaultStrategy
|
||||
- UserIdStrategy
|
||||
- FlexibleRolloutStrategy
|
||||
- GradualRolloutUserIdStrategy
|
||||
- GradualRolloutSessionIdStrategy
|
||||
- GradualRolloutRandomStrategy
|
||||
- RemoteAddressStrategy
|
||||
- ApplicationHostnameStrategy
|
||||
|
||||
Read more about the strategies in [the activation strategies document](../../reference/activation-strategies.md).
|
||||
|
||||
### Unleash context {#unleash-context}
|
||||
|
||||
In order to use some of the common activation strategies you must provide an [_Unleash context_](../../reference/unleash-context.md). This client SDK allows you to send in the unleash context as part of the `isEnabled` call:
|
||||
|
||||
```go
|
||||
ctx := context.Context{
|
||||
UserId: "123",
|
||||
SessionId: "some-session-id",
|
||||
RemoteAddress: "127.0.0.1",
|
||||
}
|
||||
|
||||
unleash.IsEnabled("someToggle", unleash.WithContext(ctx))
|
||||
```
|
||||
|
||||
Read more at [github.com/Unleash/unleash-client-go](https://github.com/Unleash/unleash-client-go)
|
||||
@ -1,3 +1,5 @@
|
||||
const { readmes } = require('./readme-fns');
|
||||
|
||||
/** @type {import('@docusaurus/types').DocusaurusConfig} */
|
||||
module.exports = {
|
||||
title: 'Unleash',
|
||||
@ -54,6 +56,7 @@ module.exports = {
|
||||
'kotlin',
|
||||
'php',
|
||||
'ruby',
|
||||
'rust',
|
||||
'swift',
|
||||
],
|
||||
},
|
||||
@ -557,6 +560,17 @@ module.exports = {
|
||||
},
|
||||
},
|
||||
],
|
||||
[
|
||||
'docusaurus-plugin-remote-content',
|
||||
{
|
||||
// more info at https://github.com/rdilweb/docusaurus-plugin-remote-content#options
|
||||
name: 'content-sdks',
|
||||
sourceBaseUrl: 'https://raw.githubusercontent.com/Unleash/', // gets prepended to all of the documents when fetching
|
||||
outDir: 'docs/reference/sdks', // the base directory to output to.
|
||||
documents: readmes.documentUrls, // the file names to download
|
||||
modifyContent: readmes.modifyContent,
|
||||
},
|
||||
],
|
||||
],
|
||||
themes: ['docusaurus-theme-openapi-docs'], // Allows use of @theme/ApiItem and other components
|
||||
};
|
||||
|
||||
@ -30,6 +30,7 @@
|
||||
"browserslist": "^4.16.5",
|
||||
"clsx": "1.2.1",
|
||||
"docusaurus-plugin-openapi-docs": "1.5.0",
|
||||
"docusaurus-plugin-remote-content": "^3.1.0",
|
||||
"docusaurus-theme-openapi-docs": "1.5.0",
|
||||
"file-loader": "6.2.0",
|
||||
"immer": "^9.0.6",
|
||||
|
||||
89
website/readme-fns.js
Normal file
89
website/readme-fns.js
Normal file
@ -0,0 +1,89 @@
|
||||
// Type definitions
|
||||
//
|
||||
// type Readme = {
|
||||
// // This is the name that is placed before "SDK" in the sidebar.
|
||||
// sidebarName: string;
|
||||
//
|
||||
// // The repo's primary branch. Falls back to "main" if nothing is defined
|
||||
// branch?: string;
|
||||
//
|
||||
// // If present, this will be used to construct the slug. If no "slugName" is
|
||||
// // defined, the `sidebarName` will be used to create the slug.
|
||||
// slugName?: string;
|
||||
// };
|
||||
//
|
||||
// type ReadmeData = Readme & { repoUrl: string };
|
||||
|
||||
// all SDK repos and what they map to for the sidebar.
|
||||
const SDKS = {
|
||||
'unleash-client-go': {
|
||||
sidebarName: 'Go',
|
||||
branch: 'v3',
|
||||
},
|
||||
'unleash-client-rust': {
|
||||
sidebarName: 'Rust',
|
||||
},
|
||||
|
||||
// 'unleash-android-proxy-sdk': {
|
||||
// sidebarName: 'Android',
|
||||
// slugName: 'android-proxy',
|
||||
// },
|
||||
};
|
||||
|
||||
function getReadmeRepoData(filename) {
|
||||
const repoName = filename.split('/')[0];
|
||||
|
||||
const repoData = SDKS[repoName];
|
||||
|
||||
const repoUrl = `https://github.com/Unleash/${repoName}`;
|
||||
|
||||
if (repoData) {
|
||||
return {
|
||||
repoUrl,
|
||||
...repoData,
|
||||
slugName: (repoData.slugName ?? repoData.sidebarName).toLowerCase(),
|
||||
};
|
||||
} else return { sidebarName: repoName, repoUrl };
|
||||
}
|
||||
|
||||
const documentUrls = Object.entries(SDKS).map(
|
||||
([repo, { branch = 'main' }]) => `${repo}/${branch ?? 'main'}/README.md`,
|
||||
);
|
||||
|
||||
const modifyContent = (filename, content) => {
|
||||
const sdk = getReadmeRepoData(filename);
|
||||
|
||||
const generationTime = new Date();
|
||||
|
||||
return {
|
||||
filename: `${sdk.slugName}.md`,
|
||||
content: `---
|
||||
title: ${sdk.sidebarName} SDK
|
||||
---
|
||||
|
||||
:::info Generated content
|
||||
This document was generated from the README in the [${
|
||||
sdk.sidebarName
|
||||
} SDK's GitHub repository](${sdk.repoUrl}).
|
||||
:::
|
||||
|
||||
:::tip Connecting to Unleash
|
||||
To connect to Unleash, you'll need your Unleash API url (e.g. \`https://<your-unleash>/api\`) and a [server-side API token](/reference/api-tokens-and-client-keys.mdx#client-tokens) ([how do I create an API token?](/how-to/how-to-create-api-tokens.mdx)).
|
||||
:::
|
||||
|
||||
${content}
|
||||
|
||||
---
|
||||
|
||||
This content was generated on <time datetime="${generationTime.toISOString()}">${generationTime.toLocaleString(
|
||||
'en-gb',
|
||||
{ dateStyle: 'long', timeStyle: 'full' },
|
||||
)}</time>
|
||||
`,
|
||||
};
|
||||
};
|
||||
|
||||
module.exports.readmes = {
|
||||
documentUrls,
|
||||
modifyContent,
|
||||
};
|
||||
@ -237,11 +237,7 @@ module.exports = {
|
||||
'reference/sdks/php',
|
||||
'reference/sdks/python',
|
||||
'reference/sdks/ruby',
|
||||
{
|
||||
type: 'link',
|
||||
href: 'https://github.com/unleash/unleash-client-rust',
|
||||
label: 'Rust SDK',
|
||||
},
|
||||
'reference/sdks/rust',
|
||||
'reference/sdks/dotnet',
|
||||
],
|
||||
},
|
||||
|
||||
@ -84,12 +84,25 @@ div[class^='announcementBar_'] svg {
|
||||
}
|
||||
|
||||
main img {
|
||||
/* give images box shadows */
|
||||
box-shadow: var(--ifm-global-shadow-lw);
|
||||
}
|
||||
|
||||
main p > img {
|
||||
/* give inline images a border */
|
||||
border: var(--ifm-global-border-width) solid var(--unleash-color-gray);
|
||||
}
|
||||
|
||||
main :is(p, figure) > img {
|
||||
/* round corners to match the rest of the page */
|
||||
border-radius: var(--ifm-global-radius);
|
||||
|
||||
/* provide a background in case some images are partly transparent */
|
||||
background: var(--unleash-img-background-color);
|
||||
|
||||
/* center in-text images */
|
||||
display: block;
|
||||
margin: auto;
|
||||
border: var(--ifm-global-border-width) solid var(--unleash-color-gray);
|
||||
border-radius: var(--ifm-global-radius);
|
||||
box-shadow: var(--ifm-global-shadow-lw);
|
||||
}
|
||||
|
||||
[class^='docTitle'] {
|
||||
|
||||
@ -4642,6 +4642,13 @@ axios@^0.25.0:
|
||||
dependencies:
|
||||
follow-redirects "^1.14.7"
|
||||
|
||||
axios@^0.26.1:
|
||||
version "0.26.1"
|
||||
resolved "https://registry.yarnpkg.com/axios/-/axios-0.26.1.tgz#1ede41c51fcf51bbbd6fd43669caaa4f0495aaa9"
|
||||
integrity sha512-fPwcX4EvnSHuInCMItEhAGnaSEXRBjtzh9fOtsE6E1G6p7vl7edEeZe11QHf18+6+9gR5PbKV/sGKNaD8YaMeA==
|
||||
dependencies:
|
||||
follow-redirects "^1.14.8"
|
||||
|
||||
babel-loader@9.1.2:
|
||||
version "9.1.2"
|
||||
resolved "https://registry.yarnpkg.com/babel-loader/-/babel-loader-9.1.2.tgz#a16a080de52d08854ee14570469905a5fc00d39c"
|
||||
@ -6402,6 +6409,16 @@ docusaurus-plugin-openapi-docs@1.5.0, docusaurus-plugin-openapi-docs@^1.5.0:
|
||||
webpack "^5.61.0"
|
||||
xml-formatter "^2.6.1"
|
||||
|
||||
docusaurus-plugin-remote-content@^3.1.0:
|
||||
version "3.1.0"
|
||||
resolved "https://registry.yarnpkg.com/docusaurus-plugin-remote-content/-/docusaurus-plugin-remote-content-3.1.0.tgz#d9349da5e098ba65050c5e00ef2425f3edb5e837"
|
||||
integrity sha512-859WYmC75l9hRYa1f/2FNF+FLcKbkHCM/0dehN1Wl1fIuoFzEPf3tcWs4jcEobRHYnoMjyupqAhmu0q5j3JoIg==
|
||||
dependencies:
|
||||
axios "^0.26.1"
|
||||
picocolors "^1.0.0"
|
||||
pretty-ms "^7.0.1"
|
||||
rimraf "^3.0.2"
|
||||
|
||||
docusaurus-theme-openapi-docs@1.5.0:
|
||||
version "1.5.0"
|
||||
resolved "https://registry.yarnpkg.com/docusaurus-theme-openapi-docs/-/docusaurus-theme-openapi-docs-1.5.0.tgz#dfcfb2df92c3b87692e047b5f182688d570d75f0"
|
||||
@ -7273,7 +7290,7 @@ focus-lock@^0.8.0:
|
||||
dependencies:
|
||||
tslib "^1.9.3"
|
||||
|
||||
follow-redirects@^1.0.0, follow-redirects@^1.14.7:
|
||||
follow-redirects@^1.0.0, follow-redirects@^1.14.7, follow-redirects@^1.14.8:
|
||||
version "1.15.2"
|
||||
resolved "https://registry.yarnpkg.com/follow-redirects/-/follow-redirects-1.15.2.tgz#b460864144ba63f2681096f274c4e57026da2c13"
|
||||
integrity sha512-VQLG33o04KaQ8uYi2tVNbdrWp1QWxNNea+nmIB4EVM28v0hmP17z7aG1+wAkNzVq4KeXTq3221ye5qTJP91JwA==
|
||||
@ -10766,6 +10783,11 @@ parse-json@^5.0.0:
|
||||
json-parse-even-better-errors "^2.3.0"
|
||||
lines-and-columns "^1.1.6"
|
||||
|
||||
parse-ms@^2.1.0:
|
||||
version "2.1.0"
|
||||
resolved "https://registry.yarnpkg.com/parse-ms/-/parse-ms-2.1.0.tgz#348565a753d4391fa524029956b172cb7753097d"
|
||||
integrity sha512-kHt7kzLoS9VBZfUsiKjv43mr91ea+U05EyKkEtqp7vNbHxmaVuEqN7XxeEVnGrMtYOAxGrDElSi96K7EgO1zCA==
|
||||
|
||||
parse-numeric-range@^1.3.0:
|
||||
version "1.3.0"
|
||||
resolved "https://registry.yarnpkg.com/parse-numeric-range/-/parse-numeric-range-1.3.0.tgz#7c63b61190d61e4d53a1197f0c83c47bb670ffa3"
|
||||
@ -11421,6 +11443,13 @@ pretty-hrtime@^1.0.3:
|
||||
resolved "https://registry.yarnpkg.com/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz#b7e3ea42435a4c9b2759d99e0f201eb195802ee1"
|
||||
integrity sha512-66hKPCr+72mlfiSjlEB1+45IjXSqvVAIy6mocupoww4tBFE9R9IhwwUGoI4G++Tc9Aq+2rxOt0RFU6gPcrte0A==
|
||||
|
||||
pretty-ms@^7.0.1:
|
||||
version "7.0.1"
|
||||
resolved "https://registry.yarnpkg.com/pretty-ms/-/pretty-ms-7.0.1.tgz#7d903eaab281f7d8e03c66f867e239dc32fb73e8"
|
||||
integrity sha512-973driJZvxiGOQ5ONsFhOF/DtzPMOMtgC11kCpUrPGMTgqp2q/1gwzCquocrN33is0VZ5GFHXZYMM9l6h67v2Q==
|
||||
dependencies:
|
||||
parse-ms "^2.1.0"
|
||||
|
||||
pretty-time@^1.1.0:
|
||||
version "1.1.0"
|
||||
resolved "https://registry.yarnpkg.com/pretty-time/-/pretty-time-1.1.0.tgz#ffb7429afabb8535c346a34e41873adf3d74dd0e"
|
||||
|
||||
Loading…
Reference in New Issue
Block a user