Integrate mdbook into rustdoc

[Ppjet6]

It doesn't seem to be possible to include external markdown files without using include_file!. By this I mean your file would have to be included in your code hierarchy and it's not possible to have it as a separate hierarchy.

This could be useful for getting-started (even though usually included in the README), debugging-tips, or various tutorials.

A few ideas where this could be used:

• Be able to point rustdoc to some folder with markdown files, and it would render them all for the user to use freely in the code as normal links
• Added as an entry in the left column alongside Module, Structs, Enums, etc. Either a single entry to an index that the user would have to create, or a custom hierarchy that the user would define.

[Ppjet6]

@kinnison, @GuillaumeGomez

[steveklabnik]

There has long been a suggestion for "integrate mdbook into rustdoc and/or cargo doc", but I cannot find the existing ticket I thought we had.

[GuillaumeGomez]

I think this is a good idea and something we might want to have on the long-term. However it brings some questions:

• How should we render the markdown folder files? All in one page or a page for each file? Maybe we'd like a "book" tab in the docs? If so, what should it look like?
• To include files/folders from markdown, what syntax should we use?

[Ppjet6]

@kinnison also raised the question of what to do with these links in reexported symbols (when they reference some file local to the repo that isn't in the one that reexports).

[jyn514]

This is doc(include), right? If so I think it should be closed in favor of #44732.

[steveklabnik]

@jyn514 sorta; you can take it that way, or you can take it as "be able to make mdbooks with rustdoc too", that is, expanding rustdoc to not just be for API documentation, but for all documentation in your project.

[jyn514]

Related: rust-lang/mdBook#1356

[Susurrus]

There is a related bug to this against Cargo as well: rust-lang/cargo#739