docs: enable "remote content" plugin, add Rust SDK readme #2809
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Move all mapping into creation function.
thomasheartman
force-pushed
the
docs/include-sdk-readmes
branch
from
abd7fcd
to
7cf95dd
Compare
|
Closing in favor of the merged #2816 which builds off of this PR. |
This was referenced Jan 9, 2023
thomasheartman
added a commit
that referenced
this pull request
Jan 13, 2023
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
This PR does a few connected things:
It adds the "docusaurus-plugin-remote-content" package.
It adds configuration to make it work with Readmes found on GitHub.
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/sdksand 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 in the preview to see what it looks like live.