search

ludviglundgren / qbittorrent-cli

Cli to manage qBittorrent
MIT License
159 stars 17 forks source link

Outdated README.md and misleading command descriptions #87

Open jmechnich opened 11 months ago

jmechnich commented 11 months ago

In my humble opinion, all detailed descriptions of available commands should be removed from the README.md. The information is no longer in sync in the code (e.g. flags for individual commands have been added). It might be sufficient to list all available commands and point out the help flag.

Also, some statements in command descriptions seem to be no longer true, such as for the remove command:

Removes torrents indicated by hash, name or a prefix of either. Whitespace indicates next prefix unless argument is surrounded by quotes.

As pointed out by a user in #84, using a prefix does not work. Consequently, the descriptions should be checked and updated where required.

@ludviglundgren if you agree I am happy to prepare a PR that reflects my suggestions. On a side note, I have submitted a formula for qbittorrent-cli to Homebrew for the convenience of Mac users such as myself.

ludviglundgren commented 10 months ago

Hi @jmechnich!

Thanks for making the Homebrew formula, very useful!! Is it updated manually with new versions or do I need to setup webhooks to trigger builds or similar?

As for the docs, I went over it all with v2.0.0 but some flags might be misleading/outdated.

The bug for #84 should be fixed, I just have not been able to prioritize it.

I do not think all the commands should be removed. I often use the repo readme to check something quickly when I don't have the tool available on cli.

I'd love if you went over all of the commands and flags to check what is wrong or missing.

jmechnich commented 10 months ago

Thanks for making the Homebrew formula, very useful!! Is it updated manually with new versions or do I need to setup webhooks to trigger builds or similar?

As far as I know, there is nothing that has to be done in this repo here for keeping the Homebrew formula updated. There are command-line options to brew for the assisted creation of PRs in Homebrew/homebrew-core but I don't know for sure that there are automatic checks (it is possible though).

As for the docs, I went over it all with v2.0.0 but some flags might be misleading/outdated.

The bug for #84 should be fixed, I just have not been able to prioritize it.

I do not think all the commands should be removed. I often use the repo readme to check something quickly when I don't have the tool available on cli.

I'd love if you went over all of the commands and flags to check what is wrong or missing.

I think it should be possible to have a workflow for creating documentation pages automatically from the source (i.e. using https://about.readthedocs.com/), so the documentation is always up-to-date and does not have to be maintained separately.

I can offer to look into the specifics of how this could be done as I have no prior experience with it.

ludviglundgren commented 10 months ago

Generated docs could be something, but it's not just that, there are other comments in the README etc.

I've used Docusaurus a lot and it's pretty powerful and works well with GitHub Pages as well.

Just found this, maybe it can be useful https://github.com/awesome-golang/cobra/blob/master/doc/md_docs.md

If you want to look into it you're more than welcome to do so!