Skip to content

Commit

Permalink
docs: auto-generate remaining server-side SDK docs (#2858)
Browse files Browse the repository at this point in the history
This PR builds on the preceding doc auto-generation PRs and generates
documentation for the remaining server-side SDKs.

## Why

Refer to #2809 for more context
about generating SDK docs.

## What

-   Adds generation for the remaining server-side SDKs
- Moves generated docs from the `/reference/sdks` directory to
`/generated` directory.
- Makes sure that the URLs do not change because of the move by using
the `slug` frontmatter property.
- replaces relative github links in the markdown documents so that they
become absolute github links. (refer to the next section)
- Updates some image styling so that it doesn't apply to readme badges
(we don't need them using `display: block`)

### On link replacing:

This PR adds handling of links in the generated documentation.
Specifically, it changes links in one case:

Relative links to github. Links to code and other files in the
repository. These are prefixed with the repository's URL.

While this should work in most cases, it will fail in cases where the
links to the files are not on the repository's primary branch.
(typically main, but could also be "v3", for instance). In these cases,
the links will get a double branch in the URL and will fail. However, I
see no easy way around this (though suggestions are definitely
accepted!), and think it's a fair tradeoff. It takes the links from
"definitely failing" to "will work in the vast majority of cases".

Note: I originally also wanted to handle the case where the link is an
absolute link to docs.getunleash.io. We could turn these into relative
urls to avoid full page reloads and enjoy a smoother experience.
However, the client-side redirects don't work correctly if the relative
URL goes to a redirect page, so you end up with a 404 page. As such, I
think it's better to leave the links as absolute for now.
  • Loading branch information
thomasheartman committed Jan 13, 2023
1 parent 1faae57 commit 14e052b
Show file tree
Hide file tree
Showing 14 changed files with 100 additions and 613 deletions.
7 changes: 5 additions & 2 deletions .gitignore
Expand Up @@ -3,7 +3,6 @@ lerna-debug
npm-debug
.DS_Store
/dist
website/docs/reference/api/**/sidebar.js

# Logs
logs
Expand Down Expand Up @@ -51,4 +50,8 @@ package-lock.json
/website/i18n/*
.env

#report.json
#report.json

# Generated docs
website/docs/reference/api/**/sidebar.js
website/docs/generated
2 changes: 1 addition & 1 deletion website/docs/how-to/how-to-use-custom-strategies.md
Expand Up @@ -31,7 +31,7 @@ The steps to implement a custom strategy for your client depend on the kind of c

### Option A: Implement the strategy for a server-side client SDK {#step-3-a}

1. **Implement the custom strategy** in your [client SDK](../reference/sdks/index.md). The exact way to do this will vary depending on the specific SDK you're using, so refer to the SDK's documentation. The example below shows an example of how you'd implement a custom strategy called "TimeStamp" for the [Node.js client SDK](../reference/sdks/node.md).
1. **Implement the custom strategy** in your [client SDK](../reference/sdks/index.md). The exact way to do this will vary depending on the specific SDK you're using, so refer to the SDK's documentation. The example below shows an example of how you'd implement a custom strategy called "TimeStamp" for the [Node.js client SDK](/docs/generated/sdks/server-side/node.md).

```js
const { Strategy } = require('unleash-client');
Expand Down
116 changes: 0 additions & 116 deletions website/docs/reference/sdks/dotnet.md

This file was deleted.

18 changes: 9 additions & 9 deletions website/docs/reference/sdks/index.md
Expand Up @@ -12,14 +12,14 @@ Unleash provides official client SDKs for a number of programming language. Addi

Server-side clients run on your server and communicate directly with your Unleash instance. We provide these official clients:

- [Go SDK](go.md)
- [Java SDK](java.md)
- [Node.js SDK](node.md)
- [PHP SDK](php.md)
- [Python SDK](python.md)
- [Ruby SDK](ruby.md)
- [Rust SDK](https://github.com/unleash/unleash-client-rust)
- [.NET SDK](dotnet.md)
- [Go SDK](/docs/generated/sdks/server-side/go.md)
- [Java SDK](/docs/generated/sdks/server-side/java.md)
- [Node.js SDK](/docs/generated/sdks/server-side/node.md)
- [PHP SDK](/docs/generated/sdks/server-side/php.md)
- [Python SDK](/docs/generated/sdks/server-side/python.md)
- [Ruby SDK](/docs/generated/sdks/server-side/ruby.md)
- [Rust SDK](/docs/generated/sdks/server-side/rust.md)
- [.NET SDK](/docs/generated/sdks/server-side/dotnet.md)

### Client-side SDKs

Expand Down Expand Up @@ -51,7 +51,7 @@ If you see an item marked with a ❌ that you would find useful, feel free to re

:::

| Capability | [Java](/reference/sdks/java.md) | [Node.js](/reference/sdks/node.md) | [Go](/reference/sdks/go.md) | [Python](/reference/sdks/python.md) | [Ruby](/reference/sdks/ruby.md) | [.NET](/reference/sdks/dotnet) | [PHP](/reference/sdks/php.md) | [Rust](https://github.com/unleash/unleash-client-rust) | [Unleash Proxy](/reference/unleash-proxy.md) |
| Capability | [Java](/docs/generated/sdks/server-side/java.md) | [Node.js](/docs/generated/sdks/server-side/node.md) | [Go](/docs/generated/sdks/server-side/go.md) | [Python](/docs/generated/sdks/server-side/python.md) | [Ruby](/docs/generated/sdks/server-side/ruby.md) | [.NET](/docs/generated/sdks/server-side/dotnet.md) | [PHP](/docs/generated/sdks/server-side/php.md) | [Rust](/docs/generated/sdks/server-side/rust.md) | [Unleash Proxy](/reference/unleash-proxy.md) |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| **Category: Initialization** | | | | | | | | | |
| Async initialization ||||||||| N/A |
Expand Down
121 changes: 0 additions & 121 deletions website/docs/reference/sdks/java.md

This file was deleted.

98 changes: 0 additions & 98 deletions website/docs/reference/sdks/node.md

This file was deleted.

0 comments on commit 14e052b

Please sign in to comment.