Guide-style documentation

[steveklabnik]

Rustdoc should not just provide API documentation, but also support long-form, guide documentation.

My current thought is "use https://github.com/azerupi/mdBook as a library" to do this, but I am open to other thoughts as well.

[typesanitizer]

IMO, as someone who frequently consults the Rust book, mdBook is a good choice.

Since a couple of people mentioned math support on the forum: mdBook uses MathJax (https://github.com/azerupi/mdBook/issues/49) and not KaTeX. It seems that KaTeX is much faster than MathJax: http://www.intmath.com/cg5/katex-mathjax-comparison.php (40x speedup on my machine).

Right now, KaTeX does support different fonts like mathcal, mathfrak etc. and some (all?) amsmath environments like pmatrix, align etc.

[eliassotodo]

👍 for mdBook! I have been working on an example for the Rust Cookbook and it's been a nice tool to work with!

[mgattozzi]

Were you thinking to have a directory called something like guide and have rustdoc generate the documentation from there automatically?

[steveklabnik]

@mgattozzi previous suggestions for this feature were to have a doc directory at the top level. Haven't given it more thought than that yet!

[euclio]

Related cargo issue here: rust-lang/cargo#739

[hardvain]

@steveklabnik : Do we really need a guide style documentation feature in rustdoc? What would be a use case of it? Rather than that, I would love to see a feature where all the examples in the actual rustdoc comments are runnable and have a REPL link attached to it.

[steveklabnik]

Do we really need a guide style documentation feature in rustdoc? What would be a use case of it?

Most big projects also include guides: hyper, tokio, gtk, etc. They have to manage all of this with other tooling; a guides-like feature has been long and often requested.

where all the examples in the actual rustdoc comments are runnable and have a REPL link attached to it.

This is already the case, the issue is that the playpen doesn't support arbitrary crates. Once it does, it will all just work. 😄

[hardvain]

To the first point about most big projects having their own tooling, this makes sense. A similar thing in the scala community is https://47deg.github.io/sbt-microsites/. Lots of major scala projects use this tool to generate their websites and all of the sites have consistent looks varying only in Colors. Take a look at https://typelevel.org/cats/ for how the site looks. Perhaps we could take some inspiration from it.