add a more comprehensive README

[danieleades]

The way this is implemented currently is that the readme is generated from the readme template (README.tpl) and the crate-level doc comments in lib.rs.

see https://github.com/livioribeiro/cargo-readme for details

Doing it this way ensures that any code examples in the README are tested in CI

[OverkillGuy]

I feel out of my depth here: a simple (hardcoded, I guess?) README.md could do the job well enough, why would using a rustdoc-templated file be better?

I only see the following benefits (not applying to early project stuff):

• CI badges autogen
• Rustdoc fetching partial readme data (causes docs fragmentation = mixed bag)
• Ensures code described does compile/run as doc says

But these are trying to do the job of documentation into the readme, missing the biggest point of a README.md: it's for users to catch up with the very basics of your project:

• What is it? (2 line summary of the software's goal)
• What are dependencies/requirements? (Python with async? Requires JIRA to even work?)
• Installation process (can be abridged into "compile from source or get PPA using following commands, see docs by running make docs")
• Usage (launch arguments in common occurences, useful as quickstart)
• Documentation (just saying looks at docs/and runmake docs` is OK)
• Optional: Motivation (what itch did you want to scratch?)
• License info (duplicated from LICENCE.txt, but it's helpful to mention it in there (especially dual license etc)

[OverkillGuy]

Sidenote:

Crate-Index/README.tpl

Line 2 in 619b5cb



This mentions an old repo name (cargo-registry), which seems to redirect here.

[danieleades]

wow, comprehensive. thankyou!

There's no question that generating a README this way is over-complicated. There are two main benefits-

• testing any code examples to make sure they stay aligned with code
• removing duplication between the README and the crate-level documentation

i think there's a downside you missed too- if the crate-level documentation ever grows to include things that don't belong in the README, there's no way to exclude it using this method.

I found some other possibilities (i've not looked into them at all) - https://blog.guillaume-gomez.fr/articles/2019-04-13+Keeping+Rust+projects%27+README.md+code+examples+up-to-date

This readme generation can also be added as a custom build step, but i thought perhaps that was slightly too arcane?

---

some comments inline

I feel out of my depth here: a simple (hardcoded, I guess?) README.md could do the job well enough, why would using a rustdoc-templated file be better?

maybe its not. totally up for discussion. but don't knock it until you've tried it.

I only see the following benefits (not applying to early project stuff):

CI badges autogen
Rustdoc fetching partial readme data (causes docs fragmentation = mixed bag)
Ensures code described does compile/run as doc says

agree with all of this

But these are trying to do the job of documentation into the readme, missing the biggest point of a README.md: it's for users to catch up with the very basics of your project:

What is it? (2 line summary of the software's goal)

this should be in both the README and the crate-level docs

What are dependencies/requirements? (Python with async? Requires JIRA to even work?)

There are none. It's not common to have additional dependencies or requirements for a rust crate outside what's defined in the manifest. Depending on the crate, you will sometimes see information about which toolchain they're targeting (stable or nightly). You will sometimes see information about a minimum compiler version, but usually only if it's particularly restrictive. say, if the crate depends on a very new feature of the nightly compiler. I'm only testing nightly in CI, but i believe this crate should compile with the stable toolchain.

Installation process (can be abridged into "compile from source or get PPA using following commands, see docs by running make docs")

increasingly common to leave these out documentation for rust crates (since they're very standard), but i could definitely see a short list being appropriate-
build - cargo build
test - cargo test
generate documentation - cargo doc
bump dependencies - cargo upgrade
you see what i mean? Also installation is not covered, since this is a library. This information belongs in the README (possibly) but not the crate-level docs

Usage (launch arguments in common occurences, useful as quickstart)

since this is a library, it's not launched. It's reasonably common practice to have a concise code example of the most basic usage of the library at the top of the documentation. This would be in both the README and the crate-level docs. For detailed usage, users should refer to the rustdoc docs (usually called the 'API docs').

Documentation (just saying looks at docs/and runmake docs` is OK)

see above. A line directing users to read the API docs obviously shouldn't be in the API docs, if it can be avoided.

Optional: Motivation (what itch did you want to scratch?)
License info (duplicated from LICENCE.txt, but it's helpful to mention it in there (especially dual license etc)

seems to be uncommon in rust crates to have a LICENSE.txt file. The license is specified in the manifest. I can't comment on the legal implications of that. if a license file is added, the path to the license file should be added to the manifest. see https://doc.rust-lang.org/beta/cargo/reference/manifest.html#the-license-and-license-file-fields

[danieleades]

also i changed the crate name at one point. As you've spotted, I failed to update the link!

[danieleades]

@OverkillGuy
you might find this interesting-
example of using CI to check minimum compiler version guarantee- https://github.com/actions-rs/meta/blob/master/recipes/matrix.md

[danieleades]

righto, i'm going to try using cargo-bisect to try and find the current minimum compiler version that will build this project.

I'll add that to CI, and then anytime that changes it's a version bump.

Sound good?