Switch to #![doc = include_str!("../README.md")]

[newpavlov]

Additionally, updates README and simplifies it a bit.

[dhardy]

But why? API docs don't need licence and contributing info or the shield badges.

I understand for getrandom (where the docs largely concern platform support and configuration), but I don't think it's a useful approach in most other crates.

[newpavlov]

I think it's better for README and crate-level docs to use the same text. I also plan to add small exmples to README and it's better to test those as part of our CI. Highlighting license of the crate as part of easily visible docs is also not a bad thing in my opinion.

[dhardy]

and it's better to test those as part of our CI

That can be done under a test module.

not a bad thing in my opinion

Brevity is a good thing in my opinion.

[newpavlov]

That can be done under a test module.

By copy-pasting code? It's a bad approach to keeping user-facing examples up-to-date. Granted, it's not a big concern for rand_core since we do not expect many changes, but still.

Brevity is a good thing in my opinion.

I can remove the contributing section, if you want. It would make the license section just few lines long.

[dhardy]

By copy-pasting code?

No; by using exactly the same mechanism but hiding the result by attaching it to a #[cfg(test)] item.

I can remove the contributing section, if you want.

It belongs in the README but not API docs.

You haven't convinced me that the overlap between the two is significantly greater than zero content 😄

[newpavlov]

No; by using exactly the same mechanism but hiding the result by attaching it to a #[cfg(test)] item.

How does it apply to examples in README?

It belongs in the README but not API docs.

We did not have the contributing section before now at all, so removing it from this PR should not be an issue. And is my understanding correct that you don't have objections to having the licensing section in crate-level docs?

You haven't convinced me that the overlap between the two is significantly greater than zero content

I don't see a reason why the crate introductory text should differ between crate-level docs and README. So it's certainly not zero.

Overall, I believe that #![doc = include_str!("../README.md")] results in a bit cleaner and smaller crate, so it should be used by default unless there are good reasons for doing otherwise (e.g. a big number of intra-crate links which are a bit of pain with such setup).

@josephlr @vks WDYT?

[dhardy]

How does it apply to examples in README?

You could use #![doc = include_str!("../README.md")] in a new module like tests/doc_examples.rs to test examples from the README.

And is my understanding correct that you don't have objections to having the licensing section in crate-level docs?

Not too important, but it's still extra content that doesn't need to be there. In general I think it bad to require users scroll past lots of unnecessary text when using API docs.

But some tricks can be used to hide certain content; see here: https://linebender.org/blog/doc-include/

[Bluefinger]

Just as an input for someone using the #![doc = include_str!("../README.md")] approach on their crate, I use the README as an initial quick-start guide for any users seeking to use the crate, as part of the documentation. I don't assume they land on the github page first, or even crates.io. They might have built the docs locally, or gone straight to docs.rs. And from feedback I've gotten, docs discoverability is super vital for users, so I just don't make the assumption on how a user lands on my crate, only that the initial entry point should always be the quick-start.

Less duplication is a plus, but mostly it standardises that the initial part of the docs is a quick start, with a pointer to a tutorial section. Scrolling is "cheaper" than clicking through a link, so I worry less about a bit too much content. But importantly, it ensures that no matter what, that initial landing point is the same and I can ensure the user is directed to where they need to.

This is just an example of why I went with #![doc = include_str!("../README.md")]. The tested examples do help with keeping things up to date, but mostly it was for standardised entrypoint reasons. It helps to not assume users all arrive from the same "path", I've found.

[dhardy]

Thanks for the insight @Bluefinger.

Have you tried using cargo-rdme? Example use case. This may be a good approach.

[Bluefinger]

Thanks for the insight @Bluefinger.

Have you tried using cargo-rdme? Example use case. This may be a good approach.

Looks handy, though I usually prefer not to need specific tools for this, but it being usable in CI alleviates some of those concerns.