mirror of
https://github.com/Unleash/unleash.git
synced 2024-12-22 19:07:54 +01:00
7cff6336c1
# 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. |
||
|---|---|---|
| .. | ||
| .storybook | ||
| docs | ||
| src | ||
| static | ||
| .gitignore | ||
| babel.config.js | ||
| clean-generated-docs.js | ||
| docusaurus.config.js | ||
| package.json | ||
| readme-fns.js | ||
| README.md | ||
| sidebars.js | ||
| tsconfig.json | ||
| yarn.lock | ||
Website
This website is built using Docusaurus 2, a modern static website generator.
Installation
yarn install
Local Development
yarn start
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
Build
yarn build
This command generates static content into the build directory and can be served using any static contents hosting service.
Deployment
GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.