## What
This (admittedly massive) PR updates the "physical" documentation
structure and fixes url inconsistencies and SEO problems reported by
marketing. The main points are:
- remove or move directories : advanced, user_guide, deploy, api
- move the files contained within to the appropriate one of topics,
how-to, tutorials, or reference
- update internal doc links and product links to the content
- create client-side redirects for all the urls that have changed.
A number of the files have been renamed in small ways to better match
their url and to make them easier to find. Additionally, the top-level
api directory has been moved to /reference/api/legacy/unleash (see the
discussion points section for more on this).
## Why
When moving our doc structure to diataxis a while back, we left the
"physical' files lying where they were, because it didn't matter much to
the new structure. However, that did introduce some inconsistencies with
where you place docs and how we organize them.
There's also the discrepancies in whether urls us underscores or hyphens
(which isn't necessarily the same as their file name), which has been
annoying me for a while, but now has also been raised by marketing as an
issue in terms of SEO.
## Discussion points
The old, hand-written API docs have been moved from /api to
/reference/api/legacy/unleash. There _is_ a /reference/api/unleash
directory, but this is being populated by the OpenAPI plugin, and mixing
those could only cause trouble. However, I'm unsure about putting
/legacy/ in the title, because the API isn't legacy, the docs are. Maybe
we could use another path? Like /old-docs/ or something? I'd appreciate
some input on this.
We're in the process of moving how-to guides into the how-to folder,
where they belong. This continues that work and shifts the how to guides
for SSO to the correct place and gives them appropriate names
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
## What
This PR updates the version of the docusaurus-openapi plugin we depend
on for openapi docs generation from canary version 0.0.0-514 to stable
release 1.4.4.
Also removes the manual file cleanup that was created as a workaround to
solve the issues we were having.
## Why
When we set the canary version before the weekend it was because it
contained a fix of some of the issues we were having with our docs.
That issue (and the one about file cleanup) have now been released in
v1.4.4, so we can upgrade to a stable version and remove now-redundant
cleanup code.
## Issue
So, we've got an issue with our docs build not working. When building
for production, we get an error that looks a little bit like this:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 40.85s
TypeError: source_default(...).bold is not a function
TypeError: source_default(...).bold is not a function
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
Which isn't very helpful at all. If you go into
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` and modify
the `render` function to log the actual error and remove anything
chalk-related, you get this instead:
```
$ docusaurus build
[INFO] [en] Creating an optimized production build...
✔ Client
✖ Server
Compiled with some errors in 44.62s
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38139:1593)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Actual error: Error: Unexpected: cant find current sidebar in context
at useCurrentSidebarCategory (main:11618:247)
at MDXContent (main:38513:1469)
at Fb (main:149154:44)
at Ib (main:149156:254)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
at W (main:149162:89)
at Jb (main:149165:98)
at Ib (main:149157:145)
Error: Unexpected: cant find current sidebar in context
Error: Unexpected: cant find current sidebar in context
[ERROR] Unable to build website for locale en.
[ERROR] Error: Failed to compile with errors.
at /Users/thomas/projects/work/unleash/website/node_modules/@docusaurus/core/lib/webpack/utils.js:180:24
at /Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:554:14
at processQueueWorker (/Users/thomas/projects/work/unleash/website/node_modules/webpack/lib/MultiCompiler.js:491:6)
at processTicksAndRejections (node:internal/process/task_queues:78:11)
[INFO] Docusaurus version: 2.2.0
Node version: v16.14.0
error Command failed with exit code 1.
```
That's better, but it's still not very clear.
## Getting more info
We've had problems with a similar error message before. Last time it was
caused by an empty file that docusaurus couldn't process.
A similar issue has also been described in [ this docusaurus GitHub
issue ](https://github.com/facebook/docusaurus/issues/7686). That's also
what gave me the idea of changing the logging in the dependency.
I'm currently unsure whether this is caused by the openapi docs or
something else. I've been in touch with the [openapi plugin
maintainer](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323)
and he has been able to see the same error when building for prod
locally, but it was due to some old generated files.
Worth noting: this only seems to affect the prod build. Building for dev
(`yarn docusaurus start`) works just fine. It also fails locally **and**
in CI, so it _is_ an issue.
## Updating the logging
To get better logging, you can go into the
`/node_modules/@docusaurus/core/lib/client/serverEntry.js` file and
update the `render` function from
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
// We are not using logger in this file, because it seems to fail with some
// compilers / some polyfill methods. This is very likely a bug, but in the
// long term, when we output native ES modules in SSR, the bug will be gone.
// prettier-ignore
console.error(chalk.red(`${chalk.bold('[ERROR]')} Docusaurus server-side rendering could not render static page with path ${chalk.cyan.underline(locals.path)}.`));
const isNotDefinedErrorRegex = /(?:window|document|localStorage|navigator|alert|location|buffer|self) is not defined/i;
if (isNotDefinedErrorRegex.test(err.message)) {
// prettier-ignore
console.info(`${chalk.cyan.bold('[INFO]')} It looks like you are using code that should run on the client-side only.
To get around it, try using ${chalk.cyan('`<BrowserOnly>`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#browseronly')}) or ${chalk.cyan('`ExecutionEnvironment`')} (${chalk.cyan.underline('https://docusaurus.io/docs/docusaurus-core/#executionenvironment')}).
It might also require to wrap your client code in ${chalk.cyan('`useEffect`')} hook and/or import a third-party library dynamically (if any).`);
}
throw err;
}
}
```
to
```js
export default async function render(locals) {
try {
return await doRender(locals);
}
catch (err) {
console.error(err)
throw err;
}
}
```
That'll yield the errors about the current sidebar in context.
## Root cause
Found the issue! 🙋🏼 It's explained in [this comment on the openapi docs
integration](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/323#issuecomment-1311549864)
for now, but in short: we have tags defined that we don't use. They're
being picked up by docusaurus, but don't have the proper context. That's
causing this.
The previously mentioned comment is included here for easy finding in
the future:
### Root cause explanation
The OpenAPI spec we use to generate the docs has a number of tags listed
at the root level. This is necessary for this plugin to pick up tag
categories and is, as far as I can tell, also how it _should_ be done.
However, not all of those tags are in use. Specifically, there's 2 tags
that are not.
When the plugin generates docs from the spec, it generates pages for all
endpoints and all tags and groups them by tag. However, it seems likely
that if a tag doesn't have any associated endpoints, then it won't get
added to the sidebar because there's no endpoint that references it.
But the doc files for these tags do end up lying around in the directory
regardless, and when docusaurus tries to pick up the files in the
generated directory, it also tries to pick up the unused tag files. But
because they're not part of a sidebar, they end up throwing errors
because they can't find the sidebar context.
### How I found it
The fact that I got more instances of the error message without the
sidebar ref than with it made me pay more attention to the number of
errors. I decided to check how many files were in the generated
directory and how many files were referenced from the generated sidebar.
Turns out the difference there was **2**: there were two generated files
in the directory that the sidebar didn't reference.
At this point, it was easy enough to try and delete those files before
rebuilding, and wouldn't you know: it worked!
### Our use case
Now, why do we have tags that are unused in the root spec? Can't we just
remove them?
That's a good question with a bit of a complicated answer. Unleash uses
an open core model and the OpenAPI integration is part of that open
core. The closed-source parts of Unleash are located in another repo and
extend the open-source distribution.
Because the OpenAPI spec is configured in the open-source part,
enterprise-only tags etc also need to be configured there. Then, when
the changes are absorbed into enterprise, we can use the tags there.
It gets more complicated because we use an enterprise instance to
generate the docs (because we want enterprise-endpoints to be listed
too). The instance uses the latest released instance of Unleash to have
the docs most accurately reflect the current state of things.
So, in this case, the tags have been added, but not yet used by any
endpoints, which suddenly causes this build failure. We can add the tags
to the enterprise-version, but the spec wouldn't be updated before the
next release regardless, which will probably be in a week or so.
This isn't an ideal setup, but .. it is what it is.
## Solutions and workarounds
As mentioned in the previous section, the reason the build was failing
was that there were unused tag files that docusaurus tried to include in
the build. Because they don't belong to a sidebar, the compilation
failed.
I've reported the issue to the openapi plugin maintainers and am waiting
for a response.
However, it seems that having unused root tags declared is invalid
according to the spec, so it's something we should look into fixing in
the future.
### Current workaround: cleaning script
The current workaround is to extend the api cleaning script to manually
remove the unused tag files.
### Ideal solution: filter root-level tags
Ideally, we shouldn't list unused OpenAPI tags on the root level at all.
However, because of the way we add root-level tags (as a predefined,
static lists, refer to `src/lib/openapi/index.ts`) and endpoints
(dynamically added at runtime) today, we don't really have a clear way
to filter the list of tags. This gets even more complicated when taking
the enterprise functionality and the potential extra tags they must
have.
This is, however, something that should definitely be looked into.
Working with OpenAPI across multipile repos is already troublesome, so
this is just yet another thing to look into.
## What
This change removes the use of double quotes in the
'addPublicSignupTokenUser' endpoint summary. It also changes the
original summary to a description and adds a new, shorter summary.
## Why
The OpenAPI / docusaurus integration errors out (refer to [this failed
build](https://github.com/Unleash/unleash/actions/runs/3434792557/jobs/5726445104))
if the frontmatter contains invalid characters. In this case, it's
because the automatic sidebar label contains double quotes, which it
interprets as a new key having been declared:
```
Error: Error while parsing Markdown front matter.
This can happen if you use special characters in front matter values (try using double quotes around that value).
Error: Loading of version failed for version current
Error: Unable to build website for locale en.
Error: YAMLException: can not read a block mapping entry; a multiline key may not be an implicit key at line 4, column 12:
description: "Create a user with the 'viewe ...
^
```
For some reason, I cannot reproduce this error locally. Instead, the
generation goes as expected.
---
Regarding using description instead of summary: summaries should be very
short and sweet, especially because they're also used in the generated
sidebar. Descriptions can be a bit wordier, so I added a shorter summary
for going forward.
## Generated output
This is what the old configuration would generate. Notice the
`sidedar_label` key on line 2:
```md
---
id: add-public-signup-token-user
sidebar_label: Create a user with the "viewer" root role and link them to a signup token
hide_title: true
hide_table_of_contents: true
api: {'tags': ['Public signup tokens'], 'operationId': 'addPublicSignupTokenUser', 'requestBody': {'description': 'createInvitedUserSchema', 'required': true, 'content': {'application/json': {'schema': {'type': 'object', 'additionalProperties': false, 'required': ['email', 'name', 'password'], 'properties': {'username': { 'type': 'string' }, 'email': { 'type': 'string' }, 'name': { 'type': 'string' }, 'password': { 'type': 'string' },},},},},}, 'responses': {'200': {'description': 'userSchema', 'content': {'application/json': {'schema': {'type': 'object', 'additionalProperties': false, 'required': ['id'], 'properties': {'id': {'type': 'number',}, 'isAPI': {'type': 'boolean',}, 'name': {'type': 'string',}, 'email': {'type': 'string',}, 'username': {'type': 'string',}, 'imageUrl': {'type': 'string',}, 'inviteLink': {'type': 'string',}, 'loginAttempts': {'type': 'number',}, 'emailSent': {'type': 'boolean',}, 'rootRole': {'type': 'number',}, 'seenAt': {'type': 'string', 'format': 'date-time', 'nullable': true,}, 'createdAt': {'type': 'string', 'format': 'date-time',},},},},},}, '400': {'description': 'The request data does not match what we expect.',}, '409': {'description': 'The provided resource can not be created or updated because it would conflict with the current state of the resource or with an already existing resource, respectively.',},}, 'parameters': [{'name': 'token', 'in': 'path', 'required': true, 'schema': { 'type': 'string' },},], 'description': 'Create a user with the "viewer" root role and link them to a signup token', 'method': 'post', 'path': '/invite/{token}/signup', 'servers': [{ 'url': '<your-unleash-url>' }], 'security': [{ 'apiKey': [] }], 'securitySchemes': {'apiKey': {'type': 'apiKey', 'in': 'header', 'name': 'Authorization',},}, 'jsonRequestBodyExample': {'username': 'string', 'email': 'string', 'name': 'string', 'password': 'string',}, 'info': { 'title': 'Unleash API', 'version': '4.17.2' }, 'postman': {'name': 'Create a user with the "viewer" root role and link them to a signup token', 'description': { 'type': 'text/plain' }, 'url': {'path': ['invite', ':token', 'signup'], 'host': ['{{baseUrl}}'], 'query': [], 'variable': [{'disabled': false, 'description': {'content': '(Required) ', 'type': 'text/plain',}, 'type': 'any', 'value': '', 'key': 'token',},],}, 'header': [{ 'key': 'Content-Type', 'value': 'application/json' }, { 'key': 'Accept', 'value': 'application/json' },], 'method': 'POST', 'body': {'mode': 'raw', 'raw': '""', 'options': { 'raw': { 'language': 'json' } }}}}
sidebar_class_name: 'post api-method'
info_path: docs/reference/api/unleash/unleash-api
---
import ApiTabs from "@theme/ApiTabs"; import MimeTabs from "@theme/MimeTabs"; import ParamsItem from "@theme/ParamsItem"; import ResponseSamples from "@theme/ResponseSamples"; import SchemaItem from "@theme/SchemaItem" import SchemaTabs from "@theme/SchemaTabs"; import DiscriminatorTabs from "@theme/DiscriminatorTabs"; import TabItem from "@theme/TabItem";
## Create a user with the "viewer" root role and link them to a signup token
Create a user with the "viewer" root role and link them to a signup token
<!-- And much much more! -->
```
Changed to reflect impression data in the proxy
<!-- Thanks for creating a PR! To make it easier for reviewers and
everyone else to understand what your changes relate to, please add some
relevant content to the headings below. Feel free to ignore or delete
sections that you don't think are relevant. Thank you! ❤️ -->
## About the changes
<!-- Describe the changes introduced. What are they and why are they
being introduced? Feel free to also add screenshots or steps to view the
changes if they're visual. -->
<!-- Does it close an issue? Multiple? -->
Closes #
<!-- (For internal contributors): Does it relate to an issue on public
roadmap? -->
<!--
Relates to [roadmap](https://github.com/orgs/Unleash/projects/10) item:
#
-->
### Important files
<!-- PRs can contain a lot of changes, but not all changes are equally
important. Where should a reviewer start looking to get an overview of
the changes? Are any files particularly important? -->
## Discussion points
<!-- Anything about the PR you'd like to discuss before it gets merged?
Got any questions or doubts? -->
Bumps [loader-utils](https://github.com/webpack/loader-utils) from 1.4.0
to 1.4.1.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/webpack/loader-utils/releases">loader-utils's
releases</a>.</em></p>
<blockquote>
<h2>v1.4.1</h2>
<h3><a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">1.4.1</a>
(2022-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)
(<a
href="4504e34c47">4504e34</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/webpack/loader-utils/blob/v1.4.1/CHANGELOG.md">loader-utils's
changelog</a>.</em></p>
<blockquote>
<h3><a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">1.4.1</a>
(2022-11-07)</h3>
<h3>Bug Fixes</h3>
<ul>
<li>security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)
(<a
href="4504e34c47">4504e34</a>)</li>
</ul>
<p><!-- raw HTML omitted --><!-- raw HTML omitted --></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="8f082b39f6"><code>8f082b3</code></a>
chore(release): 1.4.1</li>
<li><a
href="4504e34c47"><code>4504e34</code></a>
fix: security problem (<a
href="https://github-redirect.dependabot.com/webpack/loader-utils/issues/220">#220</a>)</li>
<li>See full diff in <a
href="https://github.com/webpack/loader-utils/compare/v1.4.0...v1.4.1">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after
your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge
and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating
it. You can achieve the same result by closing it manually
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
- `@dependabot use these labels` will set the current labels as the
default for future PRs for this repo and language
- `@dependabot use these reviewers` will set the current reviewers as
the default for future PRs for this repo and language
- `@dependabot use these assignees` will set the current assignees as
the default for future PRs for this repo and language
- `@dependabot use this milestone` will set the current milestone as the
default for future PRs for this repo and language
You can disable automated security fix PRs for this repo from the
[Security Alerts
page](https://github.com/Unleash/unleash/network/alerts).
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
## What
This change updates the description of when impression events are
fired to clarify that impression events are **not** fired in front-end
SDKs if the toggle is enabled.
It also adds a 'caution' admonition repeating this information with
some more info on why.
## Why
We've had a couple questions about this as it hasn't been clearly
stated before. Additionally, I, as a member of the team and the
original author of this document, thought that impression
events **did** fire for disabled toggles in the front-end.
As such, I consider this to be unexpected and different from what was
originally written.
## What
This change updates the availability notice and the code samples in the
import/export docs.
Specifically, the code samples have been moved to using the ApiRequest
component (and thus get examples in HTTP, cURL, and HTTPie), and the
import code sample now says which version it's using (version 3).
## Why
The import code sample didn't say which version of the data it used, so
Unleash would assume it was version 1 if you tried to run it. However,
the actual data was incompatible with the v1 data format, so you'd get
an error if you tried to actually import it.
While fixing this, I figured it'd also be alright to add some other
minor updates to bring the docs a bit more up to recent standards.
## About the changes
Prometheus metrics should not be exposed to the public. Added a note about this to inform people that internal endpoints should be dropped on external access.
## Discussion points
https://unleash-community.slack.com/archives/CGP2MCHPF/p1666688295670459
## Commits
* [docs]: Update Prometheus docs with security info
* Apply suggestions from code review
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* Add info about Prometheus security
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* Add suggest-change-store.ts and db migration
* Add suggest-change-store.ts and db migration
* change payload and event data type
* Update src/lib/db/suggest-change-store.ts
Co-authored-by: Fredrik Strand Oseberg <fredrik.no@gmail.com>
* split to 3 tables, create event on every change
* split to 3 tables, create event on every change
* Move service to enterprise
PR Comments
* PR Comments
* replacy createdBy string with User
* replace createdBy string with User
* added event to docs
* return entire changeset after adding a change
* bug fix
* bug fix
* move add change return to service layer
* PR comments
* added user id to user objects
* added user id to user objects
* added user id to user objects
* bug fix
* Rework
* Remove event and fix queries
* Update snapshot
* Remove console logs
* Fix
Co-authored-by: Fredrik Strand Oseberg <fredrik.no@gmail.com>
Co-authored-by: sjaanus <sellinjaanus@gmail.com>
* docs: add ADRs
* docs/adrs
* fix: update developer guide
* fix: add space
* Update website/docs/contributing/backend/overview.md
Co-authored-by: Ivar Conradi Østhus <ivar@getunleash.ai>
* docs: remove auto-generated sidebar
This should've been in .gitignore, but has only been ignored to the
ignore file for the website subdirectory. (This has been fixed on main.)
* docs: delete empty file
* Revert "docs: delete empty file"
This reverts commit 2435f173ff.
* docs: add frontmatter to new dev docs
* Docs(fix): add quotes around page titles
In yaml, the colon is a special character, so we need to use quotes.
* docs: fix remaining titles
* Update website/docs/contributing/backend/overview.md
Co-authored-by: Ivar Conradi Østhus <ivar@getunleash.ai>
* fix: update empty ADR
* fix: update text to reflect postgres 12
* fix: update backend overview
* fix: remove link
* fix: add form ADR
Co-authored-by: Ivar Conradi Østhus <ivar@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
## What
This PR removes or updates references in the docs to Heroku. Most of the code samples have been replaced with a more generic `unleash.example.com` url, while other references have been removed or updated.
Also removes old OpenAPI files that are out of date and redundant with the new generation.
## Background
Come November and Heroku will no longer offer free deployments of Unleash, so it's about time we remove that claim.
Links to the heroku instance are also outdated because we don't have that instance running anymore.
Finally, the OpenAPI files we do have there are old and static, so they don't match the current reality.
## Commits
* Meta: update ignore file to ignore autogenerated docs
I must've missed the ignore file when looking for patterns.
* docs: delete old openapi file.
This seems to have been a holdover from 2020 and is probably
hand-written. It has been superseded by the new autogenerated OpenAPI docs.
* docs: add notes for heroku changes to the frontend readme and pkg
* docs: remove old openapi article and add redirects to new openapi
* docs: fix link in overview doc: point to GitHub instead of heroku
* docs: update quickstart docs with new heroku details
* docs: remove reference to crashing heroku instance
* docs: remove references to herokuapp in code samples
* docs: add a placeholder comment
* docs: update references for heroku updates
* docs: keep using unleash4 for enterprise
* docs: remove start:heroku script in favor of start:sandbox
* docs: remove 'deploy on heroku button'
Now that it's not free anymore (or won't be very shortly), let's
remove it.
* docs: remove extra newline
## What
This PR
1. adds a new topic document, "The Anatomy of Unleash", which explains
how Unleash is built up as a system.
2. It also moves the "topic guides" sidebar entry from position 4 to
position 2.
3. Finally, it introduces a new `Figure` component for the
documentation, to be used with images that should be shown with
captions.
## Why
Referring to the same numbers as mentioned above, here's some background
for these changes:
1. We have gotten requests from enterprise users for a way to help new
Unleash users understand the system. Together with customer success and
customer journey, we agreed that an explanatory guide would be suitable.
It aims to give the reader an introduction into what pieces constitute
the Unleash system.
2. As part of a discussion, it was suggested to move topic guides higher
up to make them more visible. There's a few reasons for this:
1. New users of Unleash should be able to keep reading about Unleash
after the basic introductory material. When left at the bottom, topic
guides are often overlooked
2. As a justification, it was proposed that reference docs are often the
last thing you look for, so it makes sense to put that last.
3. Thinking about a new user's flow, it also makes some sense: first
read introductory material, then dive deeper into what Unleash is and
what you can use it for, then look for how-to guides if you're stuck,
and finally consult the reference material for later.
3. These diagrams aren't necessarily very self-explanatory, so adding a
caption makes a lot of sense. We didn't have a component from this
previously, so I added one.
Co-authored-by: NicolaeUnleash <103567375+NicolaeUnleash@users.noreply.github.com>
Co-authored-by: Simon Hornby <liquidwicked64@gmail.com>
## Commits
* docs: add raw export of anatomy document
* docs: move the topic guides section to near top of sidebar
* docs: add inter-doc links, some reformatting
* docs: fix broken links
* docs: add a Figure element for figures with captions
* docs: add more styling to figures
* docs: align on styles
* Fix: add fuller figure caption
* docs: rephrase heading
* Docs(test): try new way of importing images
* Docs(test): images take 3
* docs: Convert all images to using the figure component
* docs: add projects to list of top-level resources
* docs: add captions for all figures.
* docs: reorder images
* Docs(fix): typo: extra brackets
* Docs(style): remove box shadows and border on fig caption images
* Docs(chore): remove commented-out css
* Docs(refactor): use css variable for small font size.
To facilitate reusability and convey meaning.
* docs: rename anatomy doc
* docs: add note about strategies vs constraints
* Updating the images
* Apply suggestions from code review
Co-authored-by: Simon Hornby <liquidwicked64@gmail.com>
* Update website/docs/topics/the-anatomy-of-unleash.mdx
* Docs(fix): remove redundant comma
* docs: add link to node js sdk
* docs: mention that a toggle must be active in an env to be enabled
* docs: add note about environments and api keys
* Docs(reword): swap dev and prod in example
* docs: fix typo in the image
* docs: make figures in text full-width
* docs: move environments and API keys call-out to after figure
* docs: add borders to figures
* docs: add image float css idea
* Revert "docs: add image float css idea"
This reverts commit 69f27d304b.
Co-authored-by: NicolaeUnleash <103567375+NicolaeUnleash@users.noreply.github.com>
Co-authored-by: Simon Hornby <liquidwicked64@gmail.com>
## What
This change updates the details used for the doc search integration we use.
## Why
Algolia has migrated to a new doc search platform. The old credentials
still work, but the crawlers stopped working months ago. This is why
new articles don't show up in the search at all.
This update _should_ allow us to update our indices and get search
working properly again.
## What
This change adds a the min and max lengths allowed for a feature
toggle name to the feature toggle docs.
## Why
As was mentioned in #2185, this isn't documented anywhere as of today,
making it a potentially surprising issue to come across.
## What
This change adds a note to the custom activation strategies section of
the proxy docs, clarifying that the hosted proxy can not use custom
activation strategies.
## Why
We had a customer asking whether this was possible and realized it's
not stated explicitly anywhere.
* refactor: user creation screen cleanup
* feat: deprecation notice for google sso
* fix: docs openid typo
* invite link bar
* invite link page
* fix prettier docs
* regenerated openapi
* hooks for invite page api
* update openapi
* feat: invite link update
* feat: add public signup token soft-delete
* public signup frontend feature flag
* fix: new user api issues
* feat: allow for creating new user from invite link
* Feat/invite user public controller (#2106)
* added PublicInviteController for public urls
* added PublicInviteController for public urls
* added PublicInviteController for public urls
* added PublicInviteController for public urls
* fix test
* fix test
* update openapi
* refactor: password reset props
* fix: public invite schema and validation
Co-authored-by: Fredrik Strand Oseberg <fredrik.no@gmail.com>
* user invite frontend
Co-authored-by: Fredrik Strand Oseberg <fredrik.no@gmail.com>
* invite link delete confirmation dialog
* refactor: password reset action
* fix: new user invite loading state
* fix: run ts check with ci
* revert openapi changes
* fix: invite token api interface
* fix: openapi schema index
* fix: update test snapshots
* update frontend snapshot
* fix: prettier ci
* fix: updates after review
Co-authored-by: andreas-unleash <104830839+andreas-unleash@users.noreply.github.com>
Co-authored-by: Fredrik Strand Oseberg <fredrik.no@gmail.com>
* fix: change every instance of "custom constraint"
This changes every instance of "custom constraint" to "constraint" or
"strategy constraint" depending on the context.
* fix: rename custom-constraint.png to avoid confusion
* Update images-constraints
Co-authored-by: NicolaeUnleash <103567375+NicolaeUnleash@users.noreply.github.com>
## Description
Updates descriptions for "name" and "parameters" fields of custom activation strategies to clarify what they are and should be used for.
## Commits
* Updated name and parameters description
* Update website/docs/advanced/custom-activation-strategy.md
Co-authored-by: Thomas Heartman <thomasheartman+github@gmail.com>
* updated name's and parameter's description
Co-authored-by: Thomas Heartman <thomasheartman+github@gmail.com>
Co-authored-by: Thomas Heartman <thomasheartman+github@gmail.com>
* #1391: add generated doc cleaning script
## What
The cleaning script replaces all references to the Unleash ushosted instance in the
generated OpenAPI docs. It removes extra path segments (such as leading
`/ushosted` instances) and replaces the ushosted base url with something
user-agnostic.
## Why
When we host the OpenAPI docs in our official documentation, the generated
docs shouldn't necessarily point at _one specific instance_, and especially
not one that the reader is unlikely to ever use. Instead, we can remove all
the bits that are specific to the generation source we use, and make the docs
easier to use. In particular, removing the leading `/ushosted` is likely to
save us loooots of questions.
* #1391: change env var used for generating openapi from localhost
Using NODE_ENV=development doesn't necessarily make sense, so adding
an extra variable sounds reasonable to me.
* #1391: ensure that all generation commands also clean docs
* #1391: change <your-unleash-instance-url> to <your-unleash-url>
* #1391: fix ushosted replacement: not all paths start with /api
* #1391: chore: remove potential `ushosted` ending of api url
In the event that we change the base URL of OpenAPI, so that paths
don't start with `/ushosted/`, the script should still work, changing
those paths into <your-unleash-url> too.
Additionally, remove all instances of `/ushosted` that we find. In the
event that some things switch around or whatever.
## What
This PR (finally 🎉) adds generated OpenAPI docs to the official Unleash documentation. In addition to generating docs when things get merged to main, it also pushes new doc updates every day at 12:00 AM (cron `@daily`).
## Why
Now that we have OpenAPI'd all the things, we can finally start using it. This will allow us to remove hand-written api docs from the documentation and should make sure everything is always kept up to date.
### Generating from us-hosted (Unleash enterprise)
Unleash has several different versions (open source, pro, enterprise). The versions do not necessarily have the exact same api surface. In fact, the enterprise version has a few endpoints that open source does not.
Because we want to have _all_ endpoints listed in the documentation we need to generated the docs from an enterprise spec. Which brings us into the next point:
### The need for scheduled jobs
Regarding the daily scheduled tasks to update the documentation: why do we need that?
The docs are generated from the tip of the main branch. For most of the docs, this is good and something that we want. However, because the OpenAPI docs are generated from the enterprise edition, it _will not be in sync_ with the open source main branch.
Also, we probably do not want the docs to list the current bleeding edge api changes. Instead, we should prefer to use the latest enterprise release (roughly). However, because we don't get notified when this version is released and deployed, we'll instead run the API generation on a daily cadence.
This isn't the perfect solution, but it's simple and gets us 80% of the way there. More intricate solutions can be set up later.
## How
- By adding a scheduled workflow to the generate docs config.
- By adding .gitignore entries for the generated files
There's also some minor changes in styling etc.
## Dependencies
This is dependent on the changes introduced in #2062 having propagated to the enterprise release, which will probably not be for another week or so.
## Discussion
What should the API reference docs url be? I've set it to be `/reference/api/unleash/*` for now, but I'm on the fence about whether it should be `apis` or `api` in there. I also want to get the proxy and other APIs in there as we grow.
-------
## Commits
* docs: style openapi operation buttons
* docs: minor operation badge adjustments
* docs: use permalink to css snippet i copied
* docs: ignore files related to openapi generation
* docs: re-enable openapi docs
* Docs(#1391): prep for integration
* docs(#1391): run docs generation daily
* docs(#1391): add generation step to doc prs too
* docs(#1391): use the US hosted instance to generate docs
* docs(#1391): move doc generation into build command
* docs(#1391): use `/reference/api/*` instead of `/reference/apis/*`
The doc link appears to have pointed at an address that is no longer reachable. Instead, let's point to the equivalent GitHub link
Relates to and closes#2047
## What
This PR fixes some broken links that have been hanging around in the
docs for what seems like a very long time.
## Why
As discovered by the link check in #1912, there are a fair few broken
links in the docs. Everyone hates broken links because it makes it
harder to understand what they were supposed to be pointing at.
## How
There are 3 types of links that have been fixed:
- Links that should have been internal but were absolute. E.g.
`https://docs.getunleash.io/path/article` that should have been
`./article.md`
- External links that have changed, such as Slack's API description
- GitHub links to files that either no longer exist or that have been
moved. These links generally pointed to `master`/`main`, meaning
they are subject to change. They have been replaced with permalinks
pointing to specific commits.
-----
* docs: fix slack api doc link
* docs: update links in migration guide
* docs: fix broken link to ancient feature schema validation
* docs: update links to v3 auth hooks
* docs: update broken link in the go sdk article
* Fix: use permalink for GitHub link
* docs: fix wrong google auth link
* Docs: start experimenting with OpenAPI and docusaurus
* Docs: add docusaurus-theme-openapi-docs pkg
* Wip: current status
* Docs: Add 'docusaurus-plugin-api-docs'
* Move openapi into own sidebar; generate from localhost
* Chore: Update docusaurus plugin for OpenAPI
* Add website/yarn.lock to git
* Fix: fix CSS warning by using flex-end instead of end
* docs: make openapi generated code work again
* docs: make tags work properly with openapi sidebar
* Docs/chore: update OpenAPI tag scheme.
Add a whole bunch of new tags to make it easier to understand
available tags in OpenAPI.
* docs: point to new openapi docs from old api docs
* docs: typo
* Docs: link restructure
* docs: add operation indicators to openapi docs
* docs: change badge color for operations
* docs: update openapi-docs package
It now sorts tags the same as the schema
* docs: pluralize APIs in slug
* docs: update links to generated api docs
* docs: update openapi snapshot tests with new tags
* docs: conditionally load spec from localhost or from file
* docs: Remove changes relating to immediate switchover
* refactor: rename types; extract into separate file
* docs: fix api doc links
* Docs: Update compatibility matrix for php
* Docs: Update php compatibility table to include IP CIDR syntax
* Docs: Update impression data documentation
* Docs: Mention JavaScript proxy clients in impression data support
* Docs: add how-to enable the openapi spec
* Docs: fix and format how to run unleash proxy
* Fix: add backticks instead of single quotes
* Docs: remove unnecessary imports, format
* Docs: fix minor errors and update location section
* Implement user grouping feature for permissions
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Jaanus Sellin <sellinjaanus@gmail.com>
Co-authored-by: Nuno Góis <github@nunogois.com>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* docs: add svelte and vue front-end SDKs
* docs: add solid and react native SDKs as Community SDKs
* fix: reorder community SDKs so that they are sorted alphabetically
* fix: note and table
* fix: note scope, reorder community SDKs alphabetically by tech
* fix: make some text consistent across SDKs
* fix: svelte docs
* Update website/docs/sdks/proxy-svelte.md
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* fix: headings
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* refactor: add schemas to user admin controller
* refactor: remove unused SessionService
* refactor: fix search query type confusion
* refactor: add schemas to user controller (#1693)
* refactor: add schemas to user controller
* refactor: fix getAllUserSplashes method name
* refactor: name and email should not be required on create
* refactor: only some user fields may be updated
* refactor: should not require any fields on user update (#1730)
* refactor: send 400 instead of 500 on missing username and email
* refactor: should not require any fields for user update
* refactor: note that earlier versions required name or email
* refactor: merge roleDescriptionSchema and roleSchema
* Docs: Update description for create + update user
This change updates the documentation for the user creation API,
fixing errors mentioned in #1717:
- it's either `username` or `email` that is required on creation.
`name` is not required.
- `name` is the only required field when updating a user.
* docs: Fix overzealous prettier formatting
* docs: updated requirements for put: name OR email
* feat: add support for handling non standard postgres dates
* docs: update some http docs links to point to their respective https versions
* chore: refactor non standard date handling callback code to be a little clearer
* Update website/docs/deploy/configuring-unleash-v3.md
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* docs: add all /events endpoints and query params
* docs: events page skeleton structure
* docs: correct description of event payloads
* docs: add table with event properties.
* docs: remove duplicate table.
* docs: sort property table
* docs: more work on adding events: feature events
* docs: add examples for most feature events
Still missing are: events that require imports, and
feature-project-change
* docs: scaffold out all events descriptions
* docs: normalize casing
* docs: add brief descriptions to strategy and context events
* docs: Add remaining non-import event descriptions and examples
* docs: add code sample annotations for all example events.
* docs: remove all references to myself
* docs: change "toggle" -> "feature", adjust headings
The headings aren't semantic for this doc yet. We'll need to create a
new document for this.
* docs: update event type description table
* docs: change header level of event type section
* docs: add details around feature-project-change event
* docs: add import type events
* docs: use a better `createdBy` name
* docs: "sort" events so that they're in a consistent order.
* docs: remove reference to ID in addon-config-created event
* fix: drop-environments data.name all-projects -> all-environments
This is probably a bug. Should be double checked.
* docs: clarify that `data.name` is always `all-x` on drop events
* Apply suggestions from code review
Co-authored-by: sighphyre <liquidwicked64@gmail.com>
Co-authored-by: sighphyre <liquidwicked64@gmail.com>
