5 ms·
> 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 wi
by Starlevel001 4y ago
> 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.
Compare this to the Python docs, or some truly excellent Python library docs (like Trio: https://trio.readthedocs.io/en/stable/ https://trio.readthedocs.io/en/stable/, or Flask: https://flask.palletsprojects.com/en/2.1.x/ https://flask.palletsprojects.com/en/2.1.x/, or Django: https://docs.djangoproject.com/en/4.0/https://docs.djangoproject.com/en/4.0/ 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.
- pitaj 4y agoI don't find rustdoc lacking at all. It's great for API documentation and it does have intradoc links. Of course for a more serialized tutorial, rustdoc is not a good fit so we have mdbook.
- est31 4y agointradoc 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 https://github.com/rust-lang/rust/issues/74481
- deleted 4y ago[deleted]
- burntsushi 4y ago'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] [1]: https://github.com/mitmproxy/pdoc https://github.com/mitmproxy/pdoc
- yencabulator 4y agoI wish cargo doc's doctests for binaries worked. Internal APIs need loving too.
- burntsushi 4y ago'cargo doc' can produce docs for internal APIs too. On mobile or I would link the docs.
- yencabulator 4y agohttps://github.com/rust-lang/rust/issues/50784 https://github.com/rust-lang/rust/issues/50784
- epage 4y agoI 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. For examples, its improving with the example scraping work (e.g. https://docs.rs/clap/latest/clap/struct.ArgMatches.html#method.value_of https://docs.rs/clap/latest/clap/struct.ArgMatches.html#meth...) but testing of example is still lacking. I've written trycmd to help (https://github.com/assert-rs/trycmd https://github.com/assert-rs/trycmd). For derive reference and tutorial documentation, your choices are - A very long, hard to navigate top-level documentation, see https://docs.rs/structopt/latest/structopt/ https://docs.rs/structopt/latest/structopt/ - External documentation, see https://serde.rs/ https://serde.rs/ - 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 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/tutorial_derive/README.md https://github.com/clap-rs/clap/blob/master/examples/tutoria...). Its not great.
- veber-alex 4y agoYou linked to docs of 3 python projects and each one looks entirely different while the docs of all rust crates look exactly the same.
- mostlylurks 4y agoIt 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.