> This is in part because all the Rust documentation is either written in eli5 style (good luck figuring out “feature”s from that example), or you’re greeted with a formal syntax definition (technically, everything you need to know to define a “feature” is in there, but nowhere is it summarized in plain English), and nothing in between.
I wish I wish that Rust had a better documentation system. It's rather telling that any serious project has to use an entirely separate static site generator because the official doc system is so crippled.
'cargo doc' is absolutely one of my most favorite things about Rust. I've never once seen it as crippled and I've never once reached for an "entirely separate static site generator" to write docs despite maintaining several serious projects.
Writing out explicit links sucked, but we have intradoc links now. It was a huge win. But my first paragraph above was true even before intradoc links too.
Also, I hate Sphinx. It's awesome that folks have been able to use it to produce great docs, but I've never been successful in using it. I disliked it enough that I wrote my own tool for generating API documentation in Python.[1]
I find rustdoc lacking for clap. rustdoc does a good job with API reference documentation and is improving in its handling of examples but derive reference and tutorial documentation are a weak point.
- Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head)
For clap, my documentation examples are best served as programs and we've had a problem with these being broken. The Rust CLI book has a decent strategy for this by pulling in code from external files (https://rust-cli.github.io/book/index.html). I was tempted to do that for clap where example code and output (all verified via trycmd) are pulled into an mdbook site but I've stopped short and just have a README that links out to everything (https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.
All the examples are tested too. So not sure about the problem there.
Can't speak to 'derive' docs. I rarely use derives outside of what std/serde give you, and I never publish any.
But even so, I didn't say that rustdoc has zero weaknesses. :-) I said it is one of my favorite things about Rust because it is just so damn good. I've tried writing docs in several other languages before and they are leagues behind IMO. I would absolutely not call it "crippled." Not even close.
intradoc links are great, and I disagree with GP that rust's documentation tools are bad, they are pretty great. However, intra doc links have the limitation that you can't link to downstream crates: https://github.com/rust-lang/rust/issues/74481
It is a good thing that the documentation for different projects looks entirely different. I find that for me, it makes it much easier to keep track of and remember everything you're looking at if everything has a different aesthetic anchoring it, both in working memory (if you're looking at documentation for several projects simultaneously) and long-term memory.
I wish I wish that Rust had a better documentation system. It's rather telling that any serious project has to use an entirely separate static site generator because the official doc system is so crippled.
Compare this to the Python docs, or some truly excellent Python library docs (like Trio: https://trio.readthedocs.io/en/stable/, or Flask: https://flask.palletsprojects.com/en/2.1.x/, or Django: https://docs.djangoproject.com/en/4.0/https://docs.djangopro...), which are all written using Sphinx and integrate properly with crossrefs and such rather than writing manual markdown links as an example.