beets icon indicating copy to clipboard operation
beets copied to clipboard
verified publisher icon beetbox

Docs updates and improvements

Open Vrihub opened this issue 3 months ago • 3 comments

Description

Here are some documentation updates and improvements, mainly concerning beets installation and setting up a working copy for development.

f22b595 improves CONTRIBUTING.rst

  • poetry shell now requires the corresponding poetry plugin to be installed
  • The link to the pull request "great tutorial" currently points to a conference, I retrieved the original tutorial URL via archive.org and restored it. help needed: the tutorial was last updated 5 years ago, I'm not sure if it's still up-to-date with the current state of github; maybe we should point to the github help pages instead? e.g. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
  • The suggested vim editor settings were a bit outdated, the current python ftplugin shipped with vim already implements them; plus I added a couple of other plugins which might be of interest
  • pre-commit: it was just mentioned shortly in the "How to Submit Your Work" section; I moved it to the "Development Tools" section, alongside poetry and poe, and added short instructions to install and setup pre-commit

57f26fe replaces pip with pipx in the documentation files

pip has long been deprecated to install end-user applications (such as beets) in favour of pipx (see PEP 668). I replaced all the occurrences where we suggest using pip to install beets, and updated the corresponding command line examples using the correct pipx options.

In some occasions, I've kept pip examples because they are still relevant (e.g. when showing how to install extras, in case a previous installation was done using pip, see below), and added the corresponding pipx examples.

help needed: BTW installation via pip is also still suggested in the beets homepage, I think we should replace it with pipx there too.

I've also made a few related improvements to some files:

  • README.rst: just mention the 3 main ways to install (distro packages, pipx, github) and point to guides/main.rst and faq.rst for detailed instructions (avoiding duplication)
  • guides/main.rst: help needed: I don't know about installation on windows, macosx and ARM; is it OK to replace pip->pipx there too? I guess so (pipx is available for windows and macosx too), but I'd like to have confirmation; please let me know and I'll update the PR
  • plugins/index.rst: help needed: I've also added information about how to install extras into an already existing beets installation (which I think is the most common use case: the user typically installs "plain" beets, then learns about plugins later, and then has to install extras to enable plugins). I've covered three scenarios, depending on how beets was installed (via pip, pipx, or linux distribution packages), please give some feedback about that.

To Do

  • [ ] Please give feedback about the items marked above as help needed
  • [X] Documentation.
  • [ ] Changelog. (oops, I'll add it in a future commit)
  • [x] ~Tests~

Vrihub avatar Sep 19 '25 10:09 Vrihub

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Refines contributing guidelines and modernizes installation documentation by migrating from pip to pipx, streamlining README and guides, and enhancing plugin installation instructions for extras.

File-Level Changes

Change Details Files
Improve CONTRIBUTING.rst with updated guidance
  • Require poetry shell plugin explicitly
  • Restore original PR tutorial link via archive.org
  • Remove outdated Vim ftplugin suggestions
  • Relocate and expand pre-commit installation instructions
 CONTRIBUTING.rst
Overhaul main installation docs to use pipx and streamline options
  • Replace pip install commands with pipx for end-user installation
  • Consolidate install methods in README with links to detailed guides
  • Update guides/main.rst and reference/config.rst with pipx usage
  • Retain pip examples where extras installation requires it
 README.rst
docs/guides/main.rst
docs/faq.rst
docs/reference/config.rst
Migrate plugin documentation examples from pip to pipx
  • Update plugin install commands to show pipx usage
  • Ensure pip examples appear only where extras require it
 docs/plugins/absubmit.rst
docs/plugins/aura.rst
docs/plugins/autobpm.rst
docs/plugins/beatport.rst
docs/plugins/bpd.rst
docs/plugins/chroma.rst
docs/plugins/discogs.rst
docs/plugins/embedart.rst
docs/plugins/embyupdate.rst
docs/plugins/fetchart.rst
docs/plugins/kodiupdate.rst
docs/plugins/lastgenre.rst
docs/plugins/lastimport.rst
docs/plugins/lyrics.rst
docs/plugins/metasync.rst
docs/plugins/mpdstats.rst
docs/plugins/plexupdate.rst
docs/plugins/replaygain.rst
docs/plugins/scrub.rst
docs/plugins/sonosupdate.rst
docs/plugins/thumbnails.rst
docs/plugins/web.rst
Add extras installation scenarios in plugin index
  • Document extras setup for pip, pipx, and distro-package installs
  • Provide clear instructions depending on initial install method
 docs/plugins/index.rst
Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an issue from a review comment by replying to it. You can also reply to a review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull request title to generate a title at any time. You can also comment @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in the pull request body to generate a PR summary at any time exactly where you want it. You can also comment @sourcery-ai summary on the pull request to (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the pull request to resolve all Sourcery comments. Useful if you've already addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull request to dismiss all existing Sourcery reviews. Especially useful if you want to start fresh with a new review - don't forget to comment @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

  • Contact our support team for questions or feedback.
  • Visit our documentation for detailed guides and information.
  • Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai[bot] avatar Sep 19 '25 10:09 sourcery-ai[bot]

@Vrihub If you want to give this another look, I would be happy to assist you. We just merged #5807 which should make this easier now :crossed_fingers:

semohr avatar Oct 11 '25 12:10 semohr

@Vrihub If you want to give this another look, I would be happy to assist you. We just merged #5807 which should make this easier now 🤞

Sure. I was not aware of your PR when I opened this one (it was mainly motivated by re-reading the contribution guide after some time of not contributing to the project), so I preferred waiting for yours to be merged, before proceeding here.

I'll review, rebase and come up with other proposals and questions later this week.

Vrihub avatar Oct 15 '25 21:10 Vrihub