Document new Ravedude.toml manifest

[Rahix]

PR #522 introduced a Ravedude.toml manifest for configuring ravedude. This needs to be documented for users. We need to decide on where this documentation should be placed.

I personally am in favor of just putting it into the crate documentation of ravedude so it shows up on docs.rs.

Alternatives that were proposed (could also be done additionally to the above):

• mdbook documentation for ravedude (https://github.com/Rahix/avr-hal/pull/522#discussion_r1672951463)
• --help-toml option for CLI documentation (https://github.com/Rahix/avr-hal/pull/522#discussion_r1672951463)
• man page for ravedude (https://github.com/Rahix/avr-hal/pull/522#discussion_r1700550665)

Cc: @Creative0708, @tippfehlr

[tippfehlr]

I’m also in favor of docs.rs. mdbook would work as well, but seems a bit overkill for ravedude alone and is probably more work to set up. I personally think man pages would also be helpful, both for the cli and the config file.

We could use clap_mangen for the cli manpage (and clap-complete for shell completions ✨), we would only need to migrate to clap. Is there a reason not to?

I think there’s no way other than writing the ravedude.toml.5 manpage by hand, but I could do that from the other documentation. I think scdoc would be suitable (with quite readable source files).

Another point: is ravedude really related to avr-hal or would it be better to move it to it’s own repo?

edit: I’ve also just created an AUR package for ravedude at https://aur.archlinux.org/packages/ravedude

[Rahix]

Let's go with crate documentation then!

I personally think man pages would also be helpful, both for the cli and the config file.

I'm a fan of manpages as well, but deployment is difficult for tools installed via cargo. The only solution I know of would be for ravedude to carry its manpages in its belly and provide them via a ravedude --man xyz CLI flag... Not great, imo.

For distro packages like the one you crated, manpage deployment isn't an issue, of course.

The thought of a ravedude(3) and a Ravedude.toml(5) does sounds sweet though :D

we would only need to migrate to clap. Is there a reason not to?

My main reason for avoiding clap was the bloat. We don't really need advanced commandline parsing and we need it even less now that most commandline options have moved into the config file. So I'd rather keep ravedude with as few dependencies are really necessary...

Another point: is ravedude really related to avr-hal or would it be better to move it to it’s own repo?

I have conflicted feelings on this as I'm usually of the opinion that related software should rather live in one large repo than many small ones. But I do know that the rust community at large is mostly following a different approach. Not sure, I guess I'd be open to create an umbrella organization to house all the rust + avr related repos I'm currently maintaining. And then also splitting out ravedude into its own repo.

[tippfehlr]

provide them via a ravedude --man xyz CLI flag... Not great, imo.

No, please don’t :D I think I’ll write a manpage (for the config file) nonetheless and only include it in my package for now. Maybe there’ll be more packages at some point.

My main reason for avoiding clap was the bloat

Ok wow, 269 vs. 14k loc is a big difference. Still, autocompletion ^^

I have conflicted feelings on this as I'm usually of the opinion that related software should rather live in one large repo than many small ones.

I think the avr crates are fine here. Ravedude is a whole different piece of software with no dependencies(?) in this repo and seperate releases, that’s what I meant. At the moment, the AUR package needs to download the whole repo (it could use the source from crates.io though).

[Creative0708]

Hey! It's been a long time since I've contributed towards this. I've apologised before for stuff like this so I'll just say that various stuff got in the way of avr-hal for me and I hope you won't hold it against me too much.

Yeah, docs.rs sounds good. The one thing I'd worry about is being able to access the documentation offline, but it looks like tippfehlr has got that covered with the man page implementation. I'll open a draft PR with more complete coverage of the format soon-ish, hopefully.

Regarding the discussion about Ravedude being separate from avr-hal, I think both options are fine, although I would lean towards keeping ravedude within avr-hal due to Ravedude currently being heavily tied to Rust and avr-hal. Plans to turn ravedude into a standalone avrdude alternative would be another discussion entirely.

[Rahix]

Hello!

So as I just noticed while doing the release earlier, docs.rs doesn't work because it doesn't seem to build documentation for bin crates. Oh well. I've copied the docs I have written into a section of the README and inserted links to that whereever appropriate. I think this works well enough for the time being.