rustdoc
rustdoc copied to clipboard
steveklabnik
Guide-style documentation
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.
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 guide and have rustdoc generate the documentation from there automatically?
@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!
@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.
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. 😄
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.