docs: consider adding a table of contents to readmes

[hawkw]

Feature Request

Crates

• tracing
• root readme

Motivation

Now that we've added a lot of usage examples to the repo root and tracing crate's README files, they've started to get quite long.

Proposal

Maybe we should add a table of contents with links to the different sections?

Alternatives

Alternatively, we could..."not do this".

[hawkw]

cc @davidbarsky @yaahc do you have opinions on whether this is a good idea?

[hawkw]

The tracing crate's top-level RustDoc has gotten quite long as well...perhaps it also ought to have a table of contents?

[davidbarsky]

@hawkw I think it's a good idea, but one of the the issues I ran into with #496 is that I needed to update the doc in three places—the root README.md, tracing/README.md, and tracing/src/lib.rs, and that's a pain. We should be able to update the docs in one spot and have that change reflected everywhere.

To the best of my knowledge, we either need to use https://github.com/livioribeiro/cargo-readme or rely on the unstable rust-lang/rust#44732.

[hawkw]

@davidbarsky hmm, I think feature(external_doc) might be okay — since docs.rs always builds on nightly, and we're planning on adding doc_cfg attributes (#440) which also require a feature flag. So, I think we can have full docs builds require a cfg passed to RUSTDOC_FLAGS, making it okay to use external_doc...

[davidbarsky]

@hawkw Gotcha. I forgot that we were planning to use unstable features for building docs. As @mystor noted, #[doc(include = "")] will be replaced by #[doc(include_str = "")] at some point, so we can update to that form when that feature is ready. It probably won't be too big of a change.

[mystor]

As @mystor noted, #[doc(include = "")] will be replaced by #[doc(include_str = "")] at some point, so we can update to that form when that feature is ready. It probably won't be too big of a change.

The proposed replacement is actually #[doc = include_str!("")], from rust-lang/rust#44732 (comment) and rust-lang/rust#67121.

[davidbarsky]

D'oh, thank you.

[hawkw]

FWIW, I don't think it is as critical to have a ToC in the lib docs as it is in the README...there's more stuff in the README.

[yaahc]

I'm a big fan of having a single source of information, though I feel like you end up wanting to add a few style bits when writing a README because of how github renders them that you dont end up wanting when rendering in rustdocs because of the way rustdoc renders the markdown, mainly a header / title element.

As for the ToC, I'm not a huge fan of the idea because i worry that its a sign that the README has gotten out of hand. I tend to prefer rustdoc as a source of information about how to use the crate. I would prefer removing duplicated info from the readme and putting a more visible link to the docs over adding a ToC.

[hawkw]

Hmm. Given that the README forms the sort of "splash page" that you see immediately upon looking up a crate on crates.io, I think it's important for the README to have at least one usage example — it's the first thing new users will see, so I think it's good to make a first impression. And I think there are a lot of things we ought to have in the readme that don't really belong in the lib docs, especially "meta" sections about the crate/project itself (such as "Getting Help", "Contributing", "External Resources", etc). These are important to have in the documentation, but since they aren't documenting the library's APIs, I don't think they really belong in RustDoc...

[yaahc]

Yea, there should be enough info there for people to get an idea of what your crate does, how to set it up quickly, and maybe any common questions/answers people have. But I think the readme is closer being an about page/quickstart/advertisement than being actual documentation.

Agree about the getting help, contrib, etc. That is good stuff for the README, its like repo documentation vs crate documentation. If when the README is restricted to non library documentation tasks it's still big enough to be hard to navigate then a ToC makes sense.

[hawkw]

@yaahc i do want to point out who it was that suggested we put "getting started" docs in the README in the first place :P :P :P :P