Implement markdown rendering

[critiqjo]

• Make it work for cargo doc
  • Proper html tags
  • Proper styling and ids (needs more testing)
  • Proper docblock-short rendering (ref)
• Make it work for cargo test (ref)
• Book support: MarkdownWithToc (ref)
• Pass the tests (test cases were modified -- see acc5a5f)

Compare all changes

[critiqjo]

@alexcrichton Hi! I'm trying to replace hoedown with pulldown-cmark in rustdoc. I have small doubt in the codebase: When is html::markdown::MarkdownWithToc used? I see that used from markdown::render() which is called from here. But to get there the input to rustdoc has to be a markdown file. I don't see how that will happen -- is rustdoc used to generate books? Or is it "legacy" code? Is it okay to strip all of that?

[alexcrichton]

Ah yeah we use rustdoc to generate "standalone documentation" from markdown files for the book as well as some other main docs in rust at least.

[critiqjo]

Ah yeah we use rustdoc to generate "standalone documentation" from markdown files for the book as well as some other main docs in rust at least.

Oh! I was under the impression that book generation was moved to another project like mdbook. I suspect the reason it's not done yet is due to lack of example testing in mdBook (and others?). Thanks for the reply.

[alexcrichton]

Ah yeah we may one day move to something like mdBook but right now we're just trying to get rid of our makefiles :)

[critiqjo]

@alexcrichton This fork has become almost a drop-in for the original (see the checklist at the top), except for rendering of books (fixing that is not so hard as far as I've looked). But right now, it uses 2 libraries that are in development (no releases were made yet -- hamlet and cmark-hamlet). When all that is fixed, will the Rust devs be interested in merging this?

[alexcrichton]

Nice! Also quite exciting :) For us we don't really have the ability to pull in external dependencies just yet into the build, but we're getting close! Once the new build system is up to feature parity we can start pushing on that and then finally once we've deleted the makefiles we can start pulling in external dependencies.

[critiqjo]

Sounds good! 👍

[nixpulvis]

Out of curiosity how is one supposed to build this? I currently get:

error[E0463]: can't find crate for `rustc_front`

Which makes sense considering all I did was clone this repo. It would be nice for the compiler crates to be hosted and detectable by cargo wouldn't it?

[critiqjo]

Actually, all you need to do is clone the repo, or "was". This was filter-branch-ed out of rustc repo, and then cleaned up to replace direct dependencies with the feature-equivalents. But it seems many things have changed since the last update. I'll make it up-to-date soon...

[critiqjo]

@nixpulvis Done! As of now, it is filter-branch-ed out of, effectively, this commit. And you should be able to compile it with the latest nightly.

[nixpulvis]

Still just playing around, but out of curiosity, how are you expecting people to run this? Right now I get an error about a missing crate std. The project compiles fine, it's just the call to core::run_core(paths, cfgs, externs, Input::File(cr), triple, maybe_sysroot); that produces the error below.

error[E0463]: can't find crate for `std`

[critiqjo]

Aren't you able to do cargo run -- --help to get the rustdoc help? If that worked, then replace the executable in <rustup_dir>/<toolchain>/bin/ with the compiled one if you are using rustup, otherwise replace the one in /usr/bin.