## 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 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/*`
* 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: 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>
I keep getting confused and clicking the link to the how-to guides
when I wanna go to the API reference docs and I _wrote_ the damn thing
🙈 In other words, I betcha someone else is struggling with the same
thing.
So let's try and change it to something that's harder to click by mistake.
* docs: add docs for impression data
* fix: update wording
* Update website/docs/advanced/impression_data.md
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* Update website/docs/advanced/impression_data.md
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
* docs: use hyphen instead of underscore in file name and title/slug
We've been very inconsistent with our use of separators previously
(we should try and find a standard). Hyphens are most common online,
so I've switched to that instead.
* docs: use syntax highlighting for shell commands
* docs: start outlining impression data restructure.
* docs: Add impression data info to API: create toggles
* docs: Add impression data row to compatibility matrix
* docs: restructures the impression data reference doc.
* chore: remove question callout in source material
* docs: add redirect for `impression_data` -> 'impression-data'
* docs: Add sdk availability to availability note
* chore: Fix broken doc paths.
Co-authored-by: Thomas Heartman <thomas@getunleash.ai>
The previous list order didn't seem to have any reason behind it. This
is a suggestion for new order.
Index (the introduction) is first, followed by the proxy. Then comes
all the official sdks in alphabetic order (punctuation placed before
alpha). At the end of the list is the 'community sdks' link.
I'm open to suggestions and discussion here, but was working on this
list, so thought it could use some love.
This serves two purposes:
1. For people who know the structure, it won't look like anything's
missing
2. For people who don't know the structure, it'll make community sdks
more discoverable.
This page was more or less a duplicate of the final section of the
SDK overview. I've moved the section on implementing your own SDK into
the SDK overview instead.
