Integrate mdbook into rustdoc

rust-lang / rust

Empowering everyone to build reliable and efficient software.

https://www.rust-lang.org

Other

96.44k stars 12.46k forks source link

Integrate mdbook into rustdoc #66249

Open Ppjet6 opened 4 years ago

Ppjet6 commented 4 years ago

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 commented 4 years ago

@kinnison, @GuillaumeGomez

steveklabnik commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

@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 commented 3 years ago

This is doc(include), right? If so I think it should be closed in favor of https://github.com/rust-lang/rust/issues/44732.

steveklabnik commented 3 years ago

@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 commented 3 years ago

Susurrus commented 3 years ago

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