Moving API documentation in contributing docs into rustdoc

[andrewpollack]

Problem

Capturing task from Zulip thread

"This is an exploration in moving more contributing docs into rustdoc so that intra-doc links can help us detect when the documentation goes stale. The focus of this documentation would be for our deployment of master, rather than for docs.rs, so it can be in private items, modules that only exist for master documentation, etc."

Notes

I may need guidance on which are best places to start, but from looking at the current contributing docs, the Tests section feels like a good candidate.

For my understanding, will we be shifting them to being hosted at https://doc.crates.io/contrib/apidoc/cargo/?

cc. @epage

[epage]

Probably the lowest hanging fruit is some of the content under Architecture (e.g. Package and Resolution).

Codebase Overview and testing would get into content in other crates which we aren't publishing yet and we'd just need to decide whether their URLs should be at apidoc/cargo or apidoc/<crate>. I presume the former but unsure what others thoughts are on it (@weihanglo? since you created it)

[weihanglo]

we'd just need to decide whether their URLs should be at apidoc/cargo or apidoc/<crate>

Personally prefer the former as well.

---

I'd love to see an exploration about pros and cons of the current doc and moving to rustdoc.

IIUC, the main benefit of moving to rustdoc is "helping us detect when the documentation goes stale". This is really a good point as we do link to source code when explaining the architecture. The other one might be "having a single place for Cargo documentations".

Across the Rust project, we have rustc-dev-guide, std-dev-guide, and Cargo Contributor Guide hosting their own guides in a separate mdbook. We have Rust Analyzer putting their dev guide contents right under its main git repository. It might be easier to discover and promote by putting contents in separate markdown files. People can read markdown files through GitHub web UI or their favourite markdown editors/readers.

We may need to reach a consensus in the Cargo team first. Do we need to coordinate with other projects for the format of dev guides?

[epage]

Besides links, I also feel like being in rustdoc will make it easier to keep up-to-date generally. The further away discussions of internals are from the source code, the harder to remember it exists and harder to track when a change will be relevant for it.

[weihanglo]

Note that rustc-dev-guide have got a dedicated team to maintain the contents, whereas for Cargo we don't have such a human power and probably don't need a new subteam. Also, std-dev-guide is in a quite difference situation that it's more a spin-off starting from existing docs.

[andrewpollack]

We may need to reach a consensus in the Cargo team first. Do we need to coordinate with other projects for the format of dev guides?

Have there been any updates around this? As well, if priorities have shifted, I'm happy to tackle another issue that can help the team out more!

[weihanglo]

Thank you for still being interested in this! Cargo team had a discussion about this today. The goal here is not moving the entire contributing doc into rustdoc. Instead, we want to focus on leveraging rustdoc to validate links to items and types, keeping docs specific to code up-to-date. The chapter "Architecture Overview" can be the first good candidate for this migration.

We also plan to move the chapter "Tests" into rustdoc of crate cargo-test-support, though we might hold off a while and see what's going on in rust-lang/rust#105036.

[andrewpollack]

Hey @weihanglo , thank you for the response. I took a crack at this, but realize I don't fully understand the nuances of using rustdoc for keeping the docs up to date, and what that looks like

I'll keep my eyes out for other open issues that I can help on that are more within my understanding