search

Rahix / avr-hal

embedded-hal abstractions for AVR microcontrollers
Apache License 2.0
1.32k stars 224 forks source link

Document new Ravedude.toml manifest #579

Open Rahix opened 2 months ago

Rahix commented 2 months ago

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):

Cc: @Creative0708, @tippfehlr

tippfehlr commented 2 months ago

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 commented 4 weeks ago

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 commented 4 weeks ago

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).