-
Notifications
You must be signed in to change notification settings - Fork 22
Guide-style documentation #24
Comments
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. |
👍 for mdBook! I have been working on an example for the Rust Cookbook and it's been a nice tool to work with! |
Were you thinking to have a directory called something like |
@mgattozzi previous suggestions for this feature were to have a |
Related cargo issue here: rust-lang/cargo#739 |
@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. |
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.
This is already the case, the issue is that the playpen doesn't support arbitrary crates. Once it does, it will all just work. 😄 |
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. |
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.
The text was updated successfully, but these errors were encountered: