4 ms·

'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 s

'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 ago
I 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 ago
    https://github.com/rust-lang/rust/issues/50784 https://github.com/rust-lang/rust/issues/50784
epage 4y ago
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. 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.
- burntsushi 4y ago
  > Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head) Yeah I've done this and it works fantastic: https://docs.rs/csv/latest/csv/tutorial/index.html https://docs.rs/csv/latest/csv/tutorial/index.html 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.

yencabulator 4y ago

I 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 ago
  https://github.com/rust-lang/rust/issues/50784 https://github.com/rust-lang/rust/issues/50784

epage 4y ago

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. 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.

burntsushi 4y ago
> Dummy modules to store your documentation (I've seen this used but can't remember one off the top of my head) Yeah I've done this and it works fantastic: https://docs.rs/csv/latest/csv/tutorial/index.html https://docs.rs/csv/latest/csv/tutorial/index.html 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.