Remove Rust doc shortcodes from new book #272
Conversation
|
This would be perfect to combine with a link check in CI as we have it on the main repo. |
|
Yep. I ended up having to remove a few links here because they were dead :( |
| @@ -82,9 +85,11 @@ In order to use foreign types as components, wrap them using the newtype pattern | |||
| struct Cooldown(std::time::Duration); | |||
| ``` | |||
|
|
|||
| [`Component`]: https://docs.rs/bevy/latest/bevy/ecs/component/trait.Component.html | |||
There was a problem hiding this comment.
Same thing here about pointing to 0.6
There was a problem hiding this comment.
Ok this is more compelling than I expected.
Things I like:
- We still get special formatting (I didn't know you could use code blocks as link aliases)
- We can reuse link declarations
- Legibility of prose goes way up
- Easier to run deadlink checks
Thinks I dislike:
- Less ergonomic for single-use links, especially if we did ergo improvements for short codes (default to no_mod, shorter short-code name, full paths as variable input). The proposed approach requires repeating the symbol name, repeating the crate name, specifying the url prefix (
https://docs.rs/), and adding the.htmlsuffix. - We're throwing away our ability to theme based on symbol type (ex: match struct and trait colors to our syntax highlighting theme) and to add more complicated html (ex: show docs on hover, show full path on hover, etc). Not the biggest deal in the world atm because we don't do either of those things, but it does feel like a loss.
However since we've agreed that our ideal code ref situation would require a preprocessor (which in turn, would resolve the issues above), I think I'm cool with moving in this direction in the interim. Moving to a preprocessor would require rewriting shortcodes anyway.
|
@cart links have been re-added now! There's three links from the 0.1 announcement that are unfixable: they aren't part of the public API and those links were always dead. IMO we should just leave them unlinked at this point. |
alice-i-cecile
force-pushed
the
down-with-shortcodes
branch
from
ba5b2c3 to
09810af
Compare
|
Those types are all exported in the public api of |
|
Thanks @cart; I missed them because they weren't in the |
|
I think the "fix missing Bevy 0.1 links" commit doesn't actually do that. |
|
Oops; my linter went beserk. Let me try again... |
alice-i-cecile
force-pushed
the
down-with-shortcodes
branch
from
8b3c597 to
db45cd9
Compare
|
bors r+ |
|
LOL |
|
No bors here |
- Fixes #207 # Status - [x] Split the PR - [x] Merge #272 (do first to reduce dumb merge conflicts). - [x] Fix all mdlint violations - [x] Update CI to target `master` rather than `main` (or fix the branch name per #140 ) - [x] Add local rules to ignore the same lints to improve contributor experience. I followed [these instructions](https://github.com/DavidAnson/vscode-markdownlint#configure); simply renaming the version in the .github folder didn't resolve the problem for me.
Problem
Solution