Various rustdoc improvements #9448
Conversation
alexcrichton
commented
Sep 24, 2013
alexcrichton
commented
- Migrate from pandoc to sundown. This takes rendering times of libstd from 30s to 0.5s (no longer a process-per-markdown-block).
- Change code blocks to using sundown syntax instead of pandoc syntax.
- Improve comment stripping in rustdoc (issues mentioned in commit message)
- Add an option to print rustdoc passes (so someone can know what to do with them), and remove the collapse-privacy pass (it's not clear whether the purpose is correct or not).
This also starts compiling it in the same manner as linenoise, it's just bundled with librustrt directly, and we export just a few symbols out of it.
This takes rendering times of documentation down from 30s to 0.5s. Kinda sad that none of the parallelism is needed, but oh well! Closes rust-lang#7380 cc rust-lang#3546
find src -name '*.rs' | xargs sed -i '' 's/~~~.*{\.rust}/```rust/g'
find src -name '*.rs' | xargs sed -i '' 's/ ~~~$/ ```/g'
find src -name '*.rs' | xargs sed -i '' 's/^~~~$/ ```/g'
There is less implicit removal of various comment styles, and it also removes extraneous stars occasionally found in docblock comments. It turns out that the bug for getops was just a differently formatted block. Closes rust-lang#9425 Closes rust-lang#9417
In doing so, also remove the collapse-privacy pass because it's a little over-zealous and may not be right 100% of the time (not used right now as well)
|
This (temporarily) stops syntax highlighting of examples in the docs, yeah? |
|
rustdoc currently doesn't have syntax highlighting (or at least not the ng variant) |
|
although the problem right now is out-of-date bots and that the stylesheets are missing, so we could have syntax highlighting, we just don't. |
|
In #9377, there was a concern on moving to sundown because of Markdown dialect issues. Has anything changed? |
|
It appears that sundown supports everything which we'd like to do, except that we may need to add syntax highlighting. I don't actually think the syntax highlighting will be that hard anyway, so we're not too pressed in that respect. Other than that, sundown has code blocks, tables, linking, etc, so I don't think we're missing out by moving to it. Dropping a dep on pandoc, vastly speeding up rustdoc, and possibly moving towards a more standardized markdown are good enough reasons for switching anyway. |
|
Note that Sundown is marked as deprecated: https://github.com/vmg/sundown/blob/master/CONTRIBUTING.md |
|
It's deprecated, but there is no official replacement in sight and there are maintained forks we could use instead. Pandoc is wonderful but it's way to heavy of a dependency. It's far more painful than our existing dependencies because you need GHC + cabal, and then have to build 20 Haskell libraries. |
|
I've got a lot more fixes on the way, going to lump them all in with this one, so closing for now (will make a new branch by the end of the day). |
…anishearth Replace u128 with u64 in large_enum_variant uitest A u128 has [an 8 byte alignment on x86](rust-lang#54341), but a 16 byte alignment on aarch64 which changes the size of the enums due to extra padding. This means the test fails on aarch64 changelog: none
