Docs: fix linting issues

docs/_templates/autosummary/base.rst

@@ -1,3 +1,3 @@
 {{ fullname | escape | underline}}
 .. currentmodule:: {{ module }}
-.. auto{{ objtype }}:: {{ objname }}
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/class.rst

@@ -3,10 +3,10 @@
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
-   :members:                                    <-- add at least this line
+   :members:             <-- add at least this line
    :private-members:
-   :show-inheritance:                           <-- plus I want to show inheritance...
+   :show-inheritance:    <-- plus I want to show inheritance...
-   :inherited-members:                          <-- ...and inherited members too
+   :inherited-members:   <-- ...and inherited members too
 
    {% block methods %}
    .. automethod:: __init__
@@ -25,4 +25,3 @@
    {% endblock %}
 
    .. rubric:: {{ _('Methods definition') }}
-

docs/_templates/autosummary/module.rst

@@ -8,4 +8,4 @@
 
 {%- endfor %}
 {% endif %}
-{% endblock %}
+{% endblock %}

docs/api/database.rst

@@ -44,4 +44,4 @@ Queries
 
     Query
     FieldQuery
-    AndQuery
+    AndQuery

docs/dev/library.rst

@@ -20,14 +20,15 @@ invocation of beets usually has only one :class:`Library`. It's powered by
 abstraction, something like a very minimal `ORM`_. The library is also
 responsible for handling queries to retrieve stored objects.
 
-Overview 
+Overview
 ''''''''
 
 You can add new items or albums to the library via the
 :py:meth:`Library.add` and :py:meth:`Library.add_album` methods.
 
 You may also query the library for items and albums using the
-:py:meth:`Library.items`, :py:meth:`Library.albums`, :py:meth:`Library.get_item` and :py:meth:`Library.get_album` methods.
+:py:meth:`Library.items`, :py:meth:`Library.albums`, :py:meth:`Library.get_item`
+and :py:meth:`Library.get_album` methods.
 
 Any modifications to the library must go through a
 :class:`Transaction` object, which you can get using the
@@ -64,7 +65,7 @@ We provide CRUD-like methods for interacting with the database:
 
 * :py:meth:`LibModel.store`
 * :py:meth:`LibModel.load`
-* :py:meth:`LibModel.remove` 
+* :py:meth:`LibModel.remove`
 * :py:meth:`LibModel.add`
 
 The base class :class:`beets.dbcore.Model` has a ``dict``-like interface, so

docs/dev/plugins.rst

@@ -151,50 +151,50 @@ registration process in this case::
 
 The events currently available are:
 
-* `pluginload`: called after all the plugins have been loaded after the ``beet``
+* ``pluginload``: called after all the plugins have been loaded after the
-  command starts
+  ``beet`` command starts
 
-* `import`: called after a ``beet import`` command finishes (the ``lib`` keyword
+* ``import``: called after a ``beet import`` command finishes (the ``lib``
-  argument is a Library object; ``paths`` is a list of paths (strings) that were
+  keyword argument is a Library object; ``paths`` is a list of paths (strings)
-  imported)
+  that were imported)
 
-* `album_imported`: called with an ``Album`` object every time the ``import``
+* ``album_imported``: called with an ``Album`` object every time the ``import``
   command finishes adding an album to the library. Parameters: ``lib``,
   ``album``
 
-* `album_removed`: called with an ``Album`` object every time an album is
+* ``album_removed``: called with an ``Album`` object every time an album is
   removed from the library (even when its file is not deleted from disk).
 
-* `item_copied`: called with an ``Item`` object whenever its file is copied.
+* ``item_copied``: called with an ``Item`` object whenever its file is copied.
   Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_imported`: called with an ``Item`` object every time the importer adds a
+* ``item_imported``: called with an ``Item`` object every time the importer
-  singleton to the library (not called for full-album imports). Parameters:
+  adds a singleton to the library (not called for full-album imports).
-  ``lib``, ``item``
+  Parameters: ``lib``, ``item``
 
-* `before_item_moved`: called with an ``Item`` object immediately before its
+* ``before_item_moved``: called with an ``Item`` object immediately before its
   file is moved. Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_moved`: called with an ``Item`` object whenever its file is moved.
+* ``item_moved``: called with an ``Item`` object whenever its file is moved.
   Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_linked`: called with an ``Item`` object whenever a symlink is created
+* ``item_linked``: called with an ``Item`` object whenever a symlink is created
   for a file.
   Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_hardlinked`: called with an ``Item`` object whenever a hardlink is
+* ``item_hardlinked``: called with an ``Item`` object whenever a hardlink is
   created for a file.
   Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_reflinked`: called with an ``Item`` object whenever a reflink is
+* ``item_reflinked``: called with an ``Item`` object whenever a reflink is
   created for a file.
   Parameters: ``item``, ``source`` path, ``destination`` path
 
-* `item_removed`: called with an ``Item`` object every time an item (singleton
+* ``item_removed``: called with an ``Item`` object every time an item (singleton
   or album's part) is removed from the library (even when its file is not
   deleted from disk).
 
-* `write`: called with an ``Item`` object, a ``path``, and a ``tags``
+* ``write``: called with an ``Item`` object, a ``path``, and a ``tags``
   dictionary just before a file's metadata is written to disk (i.e.,
   just before the file on disk is opened). Event handlers may change
   the ``tags`` dictionary to customize the tags that are written to the
@@ -203,84 +203,83 @@ The events currently available are:
   operation. Beets will catch that exception, print an error message
   and continue.
 
-* `after_write`: called with an ``Item`` object after a file's metadata is
+* ``after_write``: called with an ``Item`` object after a file's metadata is
   written to disk (i.e., just after the file on disk is closed).
 
-* `import_task_created`: called immediately after an import task is
+* ``import_task_created``: called immediately after an import task is
-  initialized. Plugins can use this to, for example, change imported files of a
+  initialized. Plugins can use this to, for example, change imported files of
-  task before anything else happens. It's also possible to replace the task
+  a task before anything else happens. It's also possible to replace the task
-  with another task by returning a list of tasks. This list can contain zero
+  with another task by returning a list of tasks. This list can contain zero or
-  or more `ImportTask`s. Returning an empty list will stop the task.
+  more ``ImportTask``. Returning an empty list will stop the task.
-  Parameters: ``task`` (an `ImportTask`) and ``session`` (an `ImportSession`).
+  Parameters: ``task`` (an ``ImportTask``) and ``session`` (an
+  ``ImportSession``).
 
-* `import_task_start`: called when before an import task begins processing.
+* ``import_task_start``: called when before an import task begins processing.
   Parameters: ``task`` and ``session``.
 
-* `import_task_apply`: called after metadata changes have been applied in an
+* ``import_task_apply``: called after metadata changes have been applied in an
   import task. This is called on the same thread as the UI, so use this
   sparingly and only for tasks that can be done quickly. For most plugins, an
   import pipeline stage is a better choice (see :ref:`plugin-stage`).
   Parameters: ``task`` and ``session``.
 
-* `import_task_before_choice`: called after candidate search for an import task
+* ``import_task_before_choice``: called after candidate search for an import
-  before any decision is made about how/if to import or tag. Can be used to
+  task before any decision is made about how/if to import or tag. Can be used
-  present information about the task or initiate interaction with the user
+  to present information about the task or initiate interaction with the user
   before importing occurs. Return an importer action to take a specific action.
   Only one handler may return a non-None result.
   Parameters: ``task`` and ``session``
 
-* `import_task_choice`: called after a decision has been made about an import
+* ``import_task_choice``: called after a decision has been made about an import
   task. This event can be used to initiate further interaction with the user.
   Use ``task.choice_flag`` to determine or change the action to be
   taken. Parameters: ``task`` and ``session``.
 
-* `import_task_files`: called after an import task finishes manipulating the
+* ``import_task_files``: called after an import task finishes manipulating the
   filesystem (copying and moving files, writing metadata tags). Parameters:
   ``task`` and ``session``.
 
-* `library_opened`: called after beets starts up and initializes the main
+* ``library_opened``: called after beets starts up and initializes the main
   Library object. Parameter: ``lib``.
 
-* `database_change`: a modification has been made to the library database. The
+* ``database_change``: a modification has been made to the library database. The
   change might not be committed yet. Parameters: ``lib`` and ``model``.
 
-* `cli_exit`: called just before the ``beet`` command-line program exits.
+* ``cli_exit``: called just before the ``beet`` command-line program exits.
   Parameter: ``lib``.
 
-* `import_begin`: called just before a ``beet import`` session starts up.
+* ``import_begin``: called just before a ``beet import`` session starts up.
   Parameter: ``session``.
 
-* `trackinfo_received`: called after metadata for a track item has been
+* ``trackinfo_received``: called after metadata for a track item has been
   fetched from a data source, such as MusicBrainz. You can modify the tags
   that the rest of the pipeline sees on a ``beet import`` operation or during
   later adjustments, such as ``mbsync``. Slow handlers of the event can impact
   the operation, since the event is fired for any fetched possible match
-  `before` the user (or the autotagger machinery) gets to see the match.
+  ``before`` the user (or the autotagger machinery) gets to see the match.
   Parameter: ``info``.
 
-* `albuminfo_received`: like `trackinfo_received`, the event indicates new
+* ``albuminfo_received``: like ``trackinfo_received``, the event indicates new
   metadata for album items. The parameter is an ``AlbumInfo`` object instead
   of a ``TrackInfo``.
   Parameter: ``info``.
 
-* `before_choose_candidate`: called before the user is prompted for a decision
+* ``before_choose_candidate``: called before the user is prompted for a decision
   during a ``beet import`` interactive session. Plugins can use this event for
   :ref:`appending choices to the prompt <append_prompt_choices>` by returning a
   list of ``PromptChoices``. Parameters: ``task`` and ``session``.
-
+* ``mb_track_extract``: called after the metadata is obtained from MusicBrainz.
-* `mb_track_extract`: called after the metadata is obtained from
+  The parameter is a ``dict`` containing the tags retrieved from MusicBrainz for
-  MusicBrainz. The parameter is a ``dict`` containing the tags retrieved from
+  a track. Plugins must return a new (potentially empty) ``dict`` with
-  MusicBrainz for a track. Plugins must return a new (potentially empty)
+  additional ``field: value`` pairs, which the autotagger will apply to the
-  ``dict`` with additional ``field: value`` pairs, which the autotagger will
+  item, as flexible attributes if ``field`` is not a hardcoded field. Fields
-  apply to the item, as flexible attributes if ``field`` is not a hardcoded
+  already present on the track are overwritten. Parameter: ``data``
-  field. Fields already present on the track are overwritten.
+* ``mb_album_extract``: Like ``mb_track_extract``, but for album tags.
+  Overwrites tags set at the track level, if they have the same ``field``.
   Parameter: ``data``
 
-* `mb_album_extract`: Like `mb_track_extract`, but for album tags. Overwrites
+The included ``mpdupdate`` plugin provides an example use case for event
-  tags set at the track level, if they have the same ``field``.
+listeners.
-  Parameter: ``data``
-
-The included ``mpdupdate`` plugin provides an example use case for event listeners.
 
 Extend the Autotagger
 ^^^^^^^^^^^^^^^^^^^^^
@@ -330,10 +329,10 @@ Read Configuration Options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Plugins can configure themselves using the ``config.yaml`` file. You can read
-configuration values in two ways. The first is to use `self.config` within
+configuration values in two ways. The first is to use ``self.config`` within
 your plugin class. This gives you a view onto the configuration values in a
 section with the same name as your plugin's module. For example, if your plugin
-is in ``greatplugin.py``, then `self.config` will refer to options under the
+is in ``greatplugin.py``, then ``self.config`` will refer to options under the
 ``greatplugin:`` section of the config file.
 
 For example, if you have a configuration value called "foo", then users can put
@@ -343,19 +342,19 @@ this in their ``config.yaml``::
         foo: bar
 
 To access this value, say ``self.config['foo'].get()`` at any point in your
-plugin's code. The `self.config` object is a *view* as defined by the `Confuse`_
+plugin's code. The ``self.config`` object is a *view* as defined by the
-library.
+`Confuse`_ library.
 
 .. _Confuse: https://confuse.readthedocs.io/en/latest/
 
 If you want to access configuration values *outside* of your plugin's section,
-import the `config` object from the `beets` module. That is, just put ``from
+import the ``config`` object from the ``beets`` module. That is, just put ``from
 beets import config`` at the top of your plugin and access values from there.
 
 If your plugin provides configuration values for sensitive data (e.g.,
 passwords, API keys, ...), you should add these to the config so they can be
 redacted automatically when users dump their config. This can be done by
-setting each value's `redact` flag, like so::
+setting each value's ``redact`` flag, like so::
 
     self.config['password'].redact = True
 
@@ -421,7 +420,7 @@ to extend the kinds of metadata that they can easily manage.
 
 The ``MediaFile`` class uses ``MediaField`` descriptors to provide
 access to file tags. If you have created a descriptor you can add it through
-your plugins :py:meth:`beets.plugins.BeetsPlugin.add_media_field()`` method.
+your plugins :py:meth:`beets.plugins.BeetsPlugin.add_media_field()` method.
 
 .. _MediaFile: https://mediafile.readthedocs.io/en/latest/
 
@@ -462,9 +461,9 @@ Multiple stages run in parallel but each stage processes only one task at a time
 and each task is processed by only one stage at a time.
 
 Plugins provide stages as functions that take two arguments: ``config`` and
-``task``, which are ``ImportSession`` and ``ImportTask`` objects (both defined in
+``task``, which are ``ImportSession`` and ``ImportTask`` objects (both defined
-``beets.importer``). Add such a function to the plugin's ``import_stages`` field
+in ``beets.importer``). Add such a function to the plugin's ``import_stages``
-to register it::
+field to register it::
 
     from beets.plugins import BeetsPlugin
     class ExamplePlugin(BeetsPlugin):
@@ -543,11 +542,11 @@ should have an integer type::
         def album_types(self):
             return {'rating': types.INTEGER}
 
-A plugin may define two attributes: `item_types` and `album_types`.
+A plugin may define two attributes: ``item_types`` and ``album_types``.
 Each of those attributes is a dictionary mapping a flexible field name
 to a type instance. You can find the built-in types in the
-`beets.dbcore.types` and `beets.library` modules or implement your own
+``beets.dbcore.types`` and ``beets.library`` modules or implement your own
-type by inheriting from the `Type` class.
+type by inheriting from the ``Type`` class.
 
 Specifying types has several advantages:
 

docs/faq.rst

@@ -161,12 +161,11 @@ it's helpful to run on the "bleeding edge". To run the latest source:
          git clone https://github.com/beetbox/beets.git
          poetry install
 
-      This approach lets you decide where the
+      This approach lets you decide where the source is stored, with any
-      source is stored, with any changes immediately reflected in your
+      changes immediately reflected in your environment.
-      environment.
 
-More details about the beets source are available on the :doc:`developer documentation </dev/index>`
+More details about the beets source are available on the :doc:`developer
-pages.
+documentation </dev/index>` pages.
 
 
 .. _bugs:
@@ -240,7 +239,8 @@ move all your files.
 If you've already moved your music *outside* of beets, you have a few options:
 
 - Move the music back (with an ordinary ``mv``) and then use the above steps.
-- Delete your database and re-create it from the new paths using ``beet import -AWC``.
+- Delete your database and re-create it from the new paths using ``beet import
+  -AWC``.
 - Resort to manually modifying the SQLite database (not recommended).
 
 

docs/guides/advanced.rst

@@ -109,8 +109,8 @@ using the :ref:`modify-cmd` command::
 
 By default, beets will show you the changes that are about to be applied and ask
 if you really want to apply them to all, some or none of the items or albums.
-You can type y for "yes", n for "no", or s for "select". If you choose the latter,
+You can type y for "yes", n for "no", or s for "select". If you choose the
-the command will prompt you for each individual matching item or album.
+latter, the command will prompt you for each individual matching item or album.
 
 Then :doc:`query </reference/query>` your music just as you would with any
 other field::

docs/guides/main.rst

@@ -21,17 +21,14 @@ Beets works on Python 3.8 or later.
 * On **Debian or Ubuntu**, depending on the version, beets is available as an
   official package (`Debian details`_, `Ubuntu details`_), so try typing:
   ``apt-get install beets``. But the version in the repositories might lag
-  behind, so make sure you read the right version of these docs. If you want
+  behind, so make sure you read the right version of these docs. If you want the
-  the latest version, you can get everything you need to install with pip
+  latest version, you can get everything you need to install with pip as
-  as described below by running:
+  described below by running: ``apt-get install python-dev python-pip``
-  ``apt-get install python-dev python-pip``
+* On **Arch Linux**, `beets is in [extra] <Arch extra_>`_, so just run ``pacman
-
+  -S beets``. (There's also a bleeding-edge `dev package <AUR_>`_ in the AUR,
-* On **Arch Linux**, `beets is in [extra] <Arch extra_>`_, so just run ``pacman -S
+  which will probably set your computer on fire.)
-  beets``. (There's also a bleeding-edge `dev package <AUR_>`_ in the AUR, which will
+* On **Alpine Linux**, `beets is in the community repository <Alpine
-  probably set your computer on fire.)
+  package_>`_ and can be installed with ``apk add beets``.
-
-* On **Alpine Linux**, `beets is in the community repository <Alpine package_>`_
-  and can be installed with ``apk add beets``.
 
 * For **Gentoo Linux**, beets is in Portage as ``media-sound/beets``. Just run
   ``emerge beets`` to install. There are several USE flags available for
@@ -39,15 +36,18 @@ Beets works on Python 3.8 or later.
 
 * On **FreeBSD**, there's a `beets port <FreeBSD_>`_ at ``audio/beets``.
 
-* On **OpenBSD**, there's a `beets port <OpenBSD_>`_ can be installed with ``pkg_add beets``.
+* On **OpenBSD**, there's a `beets port <OpenBSD_>`_ can be installed with
+  ``pkg_add beets``.
 
 * For **Slackware**, there's a `SlackBuild`_ available.
 
-* On **Fedora** 22 or later, there's a `DNF package`_ you can install with ``sudo dnf install beets beets-plugins beets-doc``.
+* On **Fedora** 22 or later, there's a `DNF package`_ you can install with
+  ``sudo dnf install beets beets-plugins beets-doc``.
 
 * On **Solus**, run ``eopkg install beets``.
 
-* On **NixOS**, there's a `package <NixOS_>`_ you can install with ``nix-env -i beets``.
+* On **NixOS**, there's a `package <NixOS_>`_ you can install with ``nix-env -i
+  beets``.
 
 .. _DNF package: https://packages.fedoraproject.org/pkgs/beets/
 .. _SlackBuild: https://slackbuilds.org/repository/14.2/multimedia/beets/
@@ -103,13 +103,13 @@ get it right:
    box. If you do that, you can skip the next step.
 
 2. If you haven't done so already, set your ``PATH`` environment variable to
-   include Python and its scripts. To do so, open the "Settings" application, 
+   include Python and its scripts. To do so, open the "Settings" application,
-   then access the "System" screen, then access the "About" tab, and then hit 
+   then access the "System" screen, then access the "About" tab, and then hit
-   "Advanced system settings" located on the right side of the screen. This 
+   "Advanced system settings" located on the right side of the screen. This
-   should open the "System Properties" screen, then select the "Advanced" tab, 
+   should open the "System Properties" screen, then select the "Advanced" tab,
-   then hit the "Environmental Variables..." button, and then look for the PATH 
+   then hit the "Environmental Variables..." button, and then look for the PATH
-   variable in the table. Add the following to the end of the variable's value: 
+   variable in the table. Add the following to the end of the variable's value:
-   ``;C:\Python38;C:\Python38\Scripts``. You may need to adjust these paths to 
+   ``;C:\Python38;C:\Python38\Scripts``. You may need to adjust these paths to
    point to your Python installation.
 
 3. Now install beets by running: ``pip install beets``
@@ -277,19 +277,21 @@ put the field before the term, separated by a : character. So ``album:bird``
 only looks for ``bird`` in the "album" field of your songs. (Need to know more?
 :doc:`/reference/query/` will answer all your questions.)
 
-The ``beet list`` command also has an ``-a`` option, which searches for albums instead of songs::
+The ``beet list`` command also has an ``-a`` option, which searches for albums
+instead of songs::
 
     $ beet ls -a forever
     Bon Iver - For Emma, Forever Ago
     Freezepop - Freezepop Forever
 
-There's also an ``-f`` option (for *format*) that lets you specify what gets displayed in the results of a search::
+There's also an ``-f`` option (for *format*) that lets you specify what gets
+displayed in the results of a search::
 
     $ beet ls -a forever -f "[$format] $album ($year) - $artist - $title"
     [MP3] For Emma, Forever Ago (2009) - Bon Iver - Flume
     [AAC] Freezepop Forever (2011) - Freezepop - Harebrained Scheme
 
-In the format option, field references like `$format` and `$year` are filled
+In the format option, field references like ``$format`` and ``$year`` are filled
 in with data from each result. You can see a full list of available fields by
 running ``beet fields``.
 

docs/guides/tagger.rst

@@ -268,9 +268,10 @@ files, but can get confused when files don't have any metadata (or have wildly
 incorrect metadata). In this case, you need *acoustic fingerprinting*, a
 technology that identifies songs from the audio itself. With fingerprinting,
 beets can autotag files that have very bad or missing tags. The :doc:`"chroma"
-plugin </plugins/chroma>`, distributed with beets, uses the `Chromaprint`_ open-source fingerprinting technology, but it's disabled by default. That's because
+plugin </plugins/chroma>`, distributed with beets, uses the `Chromaprint`_
-it's sort of tricky to install. See the :doc:`/plugins/chroma` page for a guide
+open-source fingerprinting technology, but it's disabled by default. That's
-to getting it set up.
+because it's sort of tricky to install. See the :doc:`/plugins/chroma` page for
+a guide to getting it set up.
 
 Before you jump into acoustic fingerprinting with both feet, though, give beets
 a try without it. You may be surprised at how well metadata-based matching

docs/plugins/absubmit.rst

@@ -25,7 +25,7 @@ Then, install ``beets`` with ``absubmit`` extra
 
     pip install "beets[absubmit]"
 
-Lastly, enable the plugin in your configuration (see :ref:`using-plugins`). 
+Lastly, enable the plugin in your configuration (see :ref:`using-plugins`).
 
 
 Submitting Data

docs/plugins/acousticbrainz.rst

@@ -10,7 +10,8 @@ As an alternative the `beets-xtractor`_ plugin can be used.
 .. _AcousticBrainz: https://acousticbrainz.org/
 .. _beets-xtractor: https://github.com/adamjakab/BeetsPluginXtractor
 
-Enable the ``acousticbrainz`` plugin in your configuration (see :ref:`using-plugins`) and run it by typing::
+Enable the ``acousticbrainz`` plugin in your configuration (see
+:ref:`using-plugins`) and run it by typing::
 
     $ beet acousticbrainz [-f] [QUERY]
 

docs/plugins/albumtypes.rst

@@ -53,7 +53,8 @@ With path formats configured like::
         comp: Various Artists/$album [$year]$atypes/...
 
 
-The default plugin configuration generates paths that look like this, for example::
+The default plugin configuration generates paths that look like this, for
+example::
 
     Aphex Twin/[1993][EP][Remix] On Remixes
     Pink Floyd/[1995][Live] p·u·l·s·e

docs/plugins/autobpm.rst

@@ -1,8 +1,8 @@
 AutoBPM Plugin
 ==============
 
-The `autobpm` plugin uses the `Librosa`_ library to calculate the BPM
+The ``autobpm`` plugin uses the `Librosa`_ library to calculate the BPM
-of a track from its audio data and store it in the `bpm` field of your
+of a track from its audio data and store it in the ``bpm`` field of your
 database. It does so automatically when importing music or through
 the ``beet autobpm [QUERY]`` command.
 
@@ -26,7 +26,7 @@ configuration file. The available options are:
   Otherwise, you need to use the ``beet autobpm`` command explicitly.
   Default: ``yes``
 - **overwrite**: Calculate a BPM even for files that already have a
-  `bpm` value.
+  ``bpm`` value.
   Default: ``no``.
 - **beat_track_kwargs**: Any extra keyword arguments that you would like to
   provide to librosa's `beat_track`_ function call, for example:

docs/plugins/badfiles.rst

@@ -26,7 +26,7 @@ Custom commands will be run once for each file of the specified type, with the
 path to the file as the last argument. Commands must return a status code
 greater than zero for a file to be considered corrupt.
 
-You can run the checkers when importing files by using the `check_on_import`
+You can run the checkers when importing files by using the ``check_on_import``
 option. When on, checkers will be run against every imported file and warnings
 and errors will be presented when selecting a tagging option.
 

docs/plugins/bareasc.rst

@@ -1,11 +1,11 @@
 Bare-ASCII Search Plugin
 ========================
 
-The ``bareasc`` plugin provides a prefixed query that searches your library using
+The ``bareasc`` plugin provides a prefixed query that searches your library
-simple ASCII character matching, with accented characters folded to their base
+using simple ASCII character matching, with accented characters folded to their
-ASCII character. This can be useful if you want to find a track with accented
+base ASCII character. This can be useful if you want to find a track with
-characters in the title or artist, particularly if you are not confident
+accented characters in the title or artist, particularly if you are not
-you have the accents correct. It is also not unknown for the accents
+confident you have the accents correct. It is also not unknown for the accents
 to not be correct in the database entry or wrong in the CD information.
 
 First, enable the plugin named ``bareasc`` (see :ref:`using-plugins`).
@@ -17,11 +17,12 @@ You'll then be able to use the ``#`` prefix to use bare-ASCII matching::
 Command
 -------
 
-In addition to the query prefix, the plugin provides a utility ``bareasc`` command.
+In addition to the query prefix, the plugin provides a utility ``bareasc``
-This command is **exactly** the same as the ``beet list`` command except that
+command. This command is **exactly** the same as the ``beet list`` command
-the output is passed through the bare-ASCII transformation before being printed.
+except that the output is passed through the bare-ASCII transformation before
-This allows you to easily check what the library data looks like in bare ASCII,
+being printed. This allows you to easily check what the library data looks like
-which can be useful if you are trying to work out why a query is not matching.
+in bare ASCII, which can be useful if you are trying to work out why a query is
+not matching.
 
 Using the same example track as above::
 
@@ -37,19 +38,20 @@ Notes
 If the query string is all in lower case, the comparison ignores case as well as
 accents.
 
-The default ``bareasc`` prefix (``#``) is used as a comment character in some shells
+The default ``bareasc`` prefix (``#``) is used as a comment character in some
-so may need to be protected (for example in quotes) when typed into the command line.
+shells so may need to be protected (for example in quotes) when typed into the
+command line.
 
-The bare ASCII transliteration is quite simple. It may not give the expected output
+The bare ASCII transliteration is quite simple. It may not give the expected
-for all languages. For example, German u-umlaut ``ü`` is transformed into ASCII ``u``,
+output for all languages. For example, German u-umlaut ``ü`` is transformed into
-not into ``ue``.
+ASCII ``u``, not into ``ue``.
 
-The bare ASCII transformation also changes Unicode punctuation like double quotes,
+The bare ASCII transformation also changes Unicode punctuation like double
-apostrophes and even some hyphens. It is often best to leave out punctuation
+quotes, apostrophes and even some hyphens. It is often best to leave out
-in the queries. Note that the punctuation changes are often not even visible
+punctuation in the queries. Note that the punctuation changes are often not even
-with normal terminal fonts. You can always use the ``bareasc`` command to print the
+visible with normal terminal fonts. You can always use the ``bareasc`` command
-transformed entries and use a command like ``diff`` to compare with the output
+to print the transformed entries and use a command like ``diff`` to compare with
-from the ``list`` command.
+the output from the ``list`` command.
 
 Configuration
 -------------

docs/plugins/beatport.rst

@@ -38,6 +38,7 @@ also search for an id like so::
 Configuration
 -------------
 
-This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
+This plugin can be configured like other metadata source plugins as described in
+:ref:`metadata-source-plugin-configuration`.
 
 .. _Beatport: https://www.beatport.com/

docs/plugins/bucket.rst

@@ -30,10 +30,10 @@ The definition of a range is somewhat loose, and multiple formats are allowed:
   alphanumeric characters in the string you provide. For example, ``ABCD``,
   ``A-D``, ``A->D``, and ``[AD]`` are all equivalent.
 - For year ranges: digits characters are extracted and the two extreme years
-  define the range. For example, ``1975-77``, ``1975,76,77`` and ``1975-1977`` are
+  define the range. For example, ``1975-77``, ``1975,76,77`` and ``1975-1977``
-  equivalent. If no upper bound is given, the range is extended to current year
+  are equivalent. If no upper bound is given, the range is extended to current
-  (unless a later range is defined). For example, ``1975`` encompasses all years
+  year (unless a later range is defined). For example, ``1975`` encompasses all
-  from 1975 until now.
+  years from 1975 until now.
 
 The ``%bucket`` template function guesses whether to use alpha- or year-style
 buckets depending on the text it receives. It can guess wrong if, for example,
@@ -52,7 +52,7 @@ The available options are:
   fields.
   Default: none.
 - **bucket_alpha_regex**: A ``range: regex`` mapping (one per line) where
-  ``range`` is one of the `bucket_alpha` ranges and ``value`` is  a regex that
+  ``range`` is one of the ``bucket_alpha`` ranges and ``value`` is  a regex that
   overrides original range definition.
   Default: none.
 - **bucket_year**: Ranges to use for all substitutions occurring on the
@@ -72,6 +72,6 @@ Here's an example::
          bucket_alpha_regex:
            'A - D': ^[0-9a-dA-D…äÄ]
 
-This configuration creates five-year ranges for any input year.
+This configuration creates five-year ranges for any input year. The ``A - D``
-The `A - D` bucket now matches also all artists starting with ä or Ä and 0 to 9
+bucket now matches also all artists starting with ä or Ä and 0 to 9 and …
-and … (ellipsis). The other alpha buckets work as ranges.
+(ellipsis). The other alpha buckets work as ranges.

docs/plugins/chroma.rst

@@ -23,7 +23,7 @@ If you're willing to pay the performance cost for fingerprinting, read on!
 Installing Dependencies
 -----------------------
 
-To get fingerprinting working, you'll need to install three things: 
+To get fingerprinting working, you'll need to install three things:
 
 1. `pyacoustid`_ Python library (version 0.6 or later). You can install it by
    installing ``beets`` with ``chroma`` extra

docs/plugins/convert.rst

@@ -84,7 +84,7 @@ file. The available options are:
   defined in your config file.
   Default: ``no``.
 
-  .. note:: You probably want to use only one of the `auto` and `auto_keep`
+  .. note:: You probably want to use only one of the ``auto`` and ``auto_keep``
      options, not both. Enabling both will convert your files twice on import,
      which you probably don't want.
 
@@ -108,8 +108,10 @@ file. The available options are:
   a lower bitrate---that depends on the encoder and its configuration.
   Default: none.
 - **no_convert**: Does not transcode items matching the query string provided
-  (see :doc:`/reference/query`). For example, to not convert AAC or WMA formats, you can use ``format:AAC, format:WMA`` or
+  (see :doc:`/reference/query`). For example, to not convert AAC or WMA
-  ``path::\.(m4a|wma)$``. If you only want to transcode WMA format, you can use a negative query, e.g., ``^path::\.(wma)$``, to not convert any other format except WMA.
+  formats, you can use ``format:AAC, format:WMA`` or ``path::\.(m4a|wma)$``. If
+  you only want to transcode WMA format, you can use a negative query, e.g.,
+  ``^path::\.(wma)$``, to not convert any other format except WMA.
 - **never_convert_lossy_files**: Cross-conversions between lossy codecs---such
   as mp3, ogg vorbis, etc.---makes little sense as they will decrease quality
   even further. If set to ``yes``, lossy files are always copied.
@@ -127,18 +129,20 @@ file. The available options are:
   to their destination. This option creates symbolic links instead. Note that
   options such as ``embed`` that modify the output files after the transcoding
   step will cause the original files to be modified as well if ``link`` is
-  enabled. For this reason, album-art embedding is disabled
+  enabled. For this reason, album-art embedding is disabled for files that are
-  for files that are linked.
+  linked.
   Default: ``false``.
-- **hardlink**: This options works similar to ``link``, but it creates
+- **hardlink**: This options works similar to ``link``, but it creates hard
-  hard links instead of symlinks.
+  links instead of symlinks. This option overrides ``link``. Only works when
-  This option overrides ``link``. Only works when converting to a directory
+  converting to a directory on the same filesystem as the library.
-  on the same filesystem as the library.
   Default: ``false``.
-- **delete_originals**: Transcoded files will be copied or moved to their destination, depending on the import configuration. By default, the original files are not modified by the plugin. This option deletes the original files after the transcoding step has completed.
+- **delete_originals**: Transcoded files will be copied or moved to their
+  destination, depending on the import configuration. By default, the original
+  files are not modified by the plugin. This option deletes the original files
+  after the transcoding step has completed.
   Default: ``false``.
 - **playlist**: The name of a playlist file that should be written on each run
-  of the plugin. A relative file path (e.g `playlists/mylist.m3u8`) is allowed
+  of the plugin. A relative file path (e.g ``playlists/mylist.m3u8``) is allowed
   as well. The final destination of the playlist file will always be relative
   to the destination path (``dest``, ``--dest``, ``-d``). This configuration is
   overridden by the ``-m`` (``--playlist``) command line option.
@@ -173,7 +177,7 @@ and select a command with the ``--format`` command-line option or the
             wav: ffmpeg -i $source -y -acodec pcm_s16le $dest
 
 In this example ``beet convert`` will use the *speex* command by
-default. To convert the audio to `wav`, run ``beet convert -f wav``.
+default. To convert the audio to ``wav``, run ``beet convert -f wav``.
 This will also use the format key (``wav``) as the file extension.
 
 Each entry in the ``formats`` map consists of a key (the name of the
@@ -185,7 +189,7 @@ command to use to transcode audio. The tokens ``$source`` and ``$dest`` in the
 command are replaced with the paths to the existing and new file.
 
 The plugin in comes with default commands for the most common audio
-formats: `mp3`, `alac`, `flac`, `aac`, `opus`, `ogg`, `wma`. For
+formats: ``mp3``, ``alac``, ``flac``, ``aac``, ``opus``, ``ogg``, ``wma``. For
 details have a look at the output of ``beet config -d``.
 
 For a one-command-fits-all solution use the ``convert.command`` and

docs/plugins/deezer.rst

@@ -22,6 +22,10 @@ prompt during import::
 Configuration
 -------------
 
-This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
+This plugin can be configured like other metadata source plugins as described in
+:ref:`metadata-source-plugin-configuration`.
 
-The ``deezer`` plugin provides an additional command ``deezerupdate`` to update the ``rank`` information from Deezer. The ``rank`` (ranges from 0 to 1M) is a global indicator of a song's popularity on Deezer that is updated daily based on streams. The higher the ``rank``, the more popular the track is.
+The ``deezer`` plugin provides an additional command ``deezerupdate`` to update
+the ``rank`` information from Deezer. The ``rank`` (ranges from 0 to 1M) is a
+global indicator of a song's popularity on Deezer that is updated daily based on
+streams. The higher the ``rank``, the more popular the track is.

docs/plugins/discogs.rst

@@ -42,16 +42,17 @@ Subsequent runs will not require re-authorization.
 Authentication via Personal Access Token
 ````````````````````````````````````````
 
-As an alternative to OAuth, you can get a token from Discogs and add it to
+As an alternative to OAuth, you can get a token from Discogs and add it to your
-your configuration.
+configuration. To get a personal access token (called a "user token" in the
-To get a personal access token (called a "user token" in the `python3-discogs-client`_
+`python3-discogs-client`_ documentation):
-documentation):
 
 #. login to `Discogs`_;
-#. visit the `Developer settings page <https://www.discogs.com/settings/developers>`_;
+#. visit the `Developer settings page
+   <https://www.discogs.com/settings/developers>`_;
 #. press the *Generate new token* button;
 #. copy the generated token;
-#. place it in your configuration in the ``discogs`` section as the ``user_token`` option:
+#. place it in your configuration in the ``discogs`` section as the
+   ``user_token`` option:
 
    .. code-block:: yaml
 
@@ -62,13 +63,13 @@ documentation):
 Configuration
 -------------
 
-This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`.
+This plugin can be configured like other metadata source plugins as described in
+:ref:`metadata-source-plugin-configuration`.
 
 There is one additional option in the ``discogs:`` section, ``index_tracks``.
-Index tracks (see the `Discogs guidelines
+Index tracks (see the `Discogs guidelines`_) along with headers, mark divisions
-<https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings>`_),
+between distinct works on the same release or within works. When
-along with headers, mark divisions between distinct works on the same release
+``index_tracks`` is enabled:
-or within works. When ``index_tracks`` is enabled:
 
 .. code-block:: yaml
 
@@ -78,10 +79,7 @@ or within works. When ``index_tracks`` is enabled:
 beets will incorporate the names of the divisions containing each track into
 the imported track's title.
 
-For example, importing
+For example, importing `divisions album`_ would result in track names like:
-`this album
-<https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070>`_
-would result in track names like:
 
 .. code-block:: text
 
@@ -111,11 +109,13 @@ Other configurations available under ``discogs:`` are:
 - **separator**: How to join multiple genre and style values from Discogs into
   a string.
   Default: ``", "``
-- **search_limit**: The maximum number of results to return from Discogs. This is
+- **search_limit**: The maximum number of results to return from Discogs. This
-  useful if you want to limit the number of results returned to speed up
+  is useful if you want to limit the number of results returned to speed up
   searches.
   Default: ``5``
 
+.. _Divisions album: https://www.discogs.com/Handel-Sutherland-Kirkby-Kwella-Nelson-Watkinson-Bowman-Rolfe-Johnson-Elliott-Partridge-Thomas-The-A/release/2026070
+.. _Discogs guidelines: https://support.discogs.com/hc/en-us/articles/360005055373-Database-Guidelines-12-Tracklisting#Index_Tracks_And_Headings
 
 Troubleshooting
 ---------------
@@ -132,6 +132,7 @@ Here are two things you can try:
   your request if your clock is too out of sync.
 
 Matching tracks by Discogs ID is not yet supported. The ``--group-albums``
-option in album import mode provides an alternative to singleton mode for autotagging tracks that are not in album-related folders.
+option in album import mode provides an alternative to singleton mode for
+autotagging tracks that are not in album-related folders.
 
 .. _python3-discogs-client: https://github.com/joalla/discogs_client

docs/plugins/embedart.rst

@@ -90,15 +90,16 @@ Manually Embedding and Extracting Art
 The ``embedart`` plugin provides a couple of commands for manually managing
 embedded album art:
 
-* ``beet embedart [-f IMAGE] QUERY``: embed images in every track of the
+* ``beet embedart [-f IMAGE] QUERY``: embed images in every track of the albums
-  albums matching the query. If the ``-f`` (``--file``) option is given, then
+  matching the query. If the ``-f`` (``--file``) option is given, then use a
-  use a specific image file from the filesystem; otherwise, each album embeds
+  specific image file from the filesystem; otherwise, each album embeds its own
-  its own currently associated album art. The command prompts for confirmation
+  currently associated album art. The command prompts for confirmation before
-  before making the change unless you specify the ``-y`` (``--yes``) option.
+  making the change unless you specify the ``-y`` (``--yes``) option.
-
+* ``beet embedart [-u IMAGE_URL] QUERY``: embed image specified in the URL into
-* ``beet embedart [-u IMAGE_URL] QUERY``: embed image specified in the URL
+  every track of the albums matching the query. The ``-u`` (``--url``) option
-  into every track of the albums matching the query. The ``-u`` (``--url``) option can be used to specify the URL of the image to be used. The command prompts for confirmation before making the change unless you specify the ``-y`` (``--yes``) option.
+  can be used to specify the URL of the image to be used. The command prompts
-
+  for confirmation before making the change unless you specify the ``-y``
+  (``--yes``) option.
 * ``beet extractart [-a] [-n FILE] QUERY``: extracts the images for all albums
   matching the query. The images are placed inside the album folder. You can
   specify the destination file name using the ``-n`` option, but leave off the

docs/plugins/embyupdate.rst

@@ -22,7 +22,8 @@ that using an ``emby`` section in your ``config.yaml``
         username: user
         apikey: apikey
 
-With that all in place, you'll see beets send the "update" command to your Emby server every time you change your beets library.
+With that all in place, you'll see beets send the "update" command to your Emby
+server every time you change your beets library.
 
 .. _Emby: https://emby.media/
 
@@ -31,11 +32,13 @@ Configuration
 
 The available options under the ``emby:`` section are:
 
-- **host**: The Emby server host. You also can include ``http://`` or ``https://``.
+- **host**: The Emby server host. You also can include ``http://`` or
+  ``https://``.
   Default: ``localhost``
 - **port**: The Emby server port.
   Default: 8096
-- **username**: A username of an Emby user that is allowed to refresh the library.
+- **username**: A username of an Emby user that is allowed to refresh the
+  library.
 - **userid**: A user ID of an Emby user that is allowed to refresh the library.
   (This is only necessary for private users i.e. when the user is hidden from
   login screens)

docs/plugins/export.rst

@@ -8,8 +8,9 @@ as `JSON`_, `CSV`_, or `XML`_.
 .. _CSV: https://fileinfo.com/extension/csv
 .. _XML: https://fileinfo.com/extension/xml
 
-Enable the ``export`` plugin (see :ref:`using-plugins` for help). Then, type ``beet export`` followed by a :doc:`query </reference/query>` to get the data from
+Enable the ``export`` plugin (see :ref:`using-plugins` for help). Then, type
-your library. For example, run this::
+``beet export`` followed by a :doc:`query </reference/query>` to get the data
+from your library. For example, run this::
 
     $ beet export beatles
 
@@ -39,10 +40,10 @@ The ``export`` command has these command-line options:
 
 * ``--output`` or ``-o``: Path for an output file. If not informed, will print
   the data in the console.
-
 * ``--append``: Appends the data to the file instead of writing.
-
+* ``--format`` or ``-f``: Specifies the format the data will be exported as. If
-* ``--format`` or ``-f``: Specifies the format the data will be exported as. If not informed, JSON will be used by default. The format options include csv, json, `jsonlines <https://jsonlines.org/>`_ and xml.
+  not informed, JSON will be used by default. The format options include csv,
+  json, `jsonlines <https://jsonlines.org/>`_ and xml.
 
 Configuration
 -------------
@@ -61,8 +62,9 @@ Those options match the options from the `Python json module`_.
 Similarly, these options are available for the CSV format under the ``csv``
 key:
 
-- **delimiter**: Used as the separating character between fields. The default value is a comma (,).
+- **delimiter**: Used as the separating character between fields. The default
-- **dialect**: The kind of CSV file to produce. The default is `excel`.
+  value is a comma (,).
+- **dialect**: The kind of CSV file to produce. The default is ``excel``.
 
 These options match the options from the `Python csv module`_.
 

docs/plugins/fetchart.rst

@@ -63,7 +63,7 @@ file. The available options are:
   still be considered valid. This can be done either in pixels
   (``enforce_ratio: 10px``) or as a percentage of the longer edge
   (``enforce_ratio: 0.5%``). Default: ``no``.
-- **sources**: List of sources to search for images. An asterisk `*` expands
+- **sources**: List of sources to search for images. An asterisk ``*`` expands
   to all available sources.
   Default: ``filesystem coverart itunes amazon albumart``, i.e., everything but
   ``wikipedia``, ``google``, ``fanarttv`` and ``lastfm``. Enable those sources
@@ -143,8 +143,8 @@ be processed; otherwise, the command processes every album in your library.
 Display Only Missing Album Art
 ------------------------------
 
-Use the ``fetchart`` command with the ``-q`` switch in order to display only missing
+Use the ``fetchart`` command with the ``-q`` switch in order to display only
-art::
+missing art::
 
     $ beet fetchart [-q] [query]
 
@@ -157,12 +157,13 @@ fetched, or for which artwork could not be found will be printed.
 Image Resizing
 --------------
 
-Beets can resize images using `Pillow`_, `ImageMagick`_, or a server-side resizing
+Beets can resize images using `Pillow`_, `ImageMagick`_, or a server-side
-proxy. If either Pillow or ImageMagick is installed, beets will use those;
+resizing proxy. If either Pillow or ImageMagick is installed, beets will use
-otherwise, it falls back to the resizing proxy. If the resizing proxy is used,
+those; otherwise, it falls back to the resizing proxy. If the resizing proxy is
-no resizing is performed for album art found on the filesystem---only downloaded
+used, no resizing is performed for album art found on the filesystem---only
-art is resized. Server-side resizing can also be slower than local resizing, so
+downloaded art is resized. Server-side resizing can also be slower than local
-consider installing one of the two backends for better performance.
+resizing, so consider installing one of the two backends for better
+performance.
 
 When using ImageMagick, beets looks for the ``convert`` executable in your path.
 On some versions of Windows, the program can be shadowed by a system-provided
@@ -258,7 +259,8 @@ the list of sources in your configuration.
 Spotify
 '''''''
 
-Spotify backend is enabled by default and will update album art if a valid Spotify album id is found.
+Spotify backend is enabled by default and will update album art if a valid
+Spotify album id is found.
 
 .. _pip: https://pip.pypa.io
 .. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
@@ -266,10 +268,10 @@ Spotify backend is enabled by default and will update album art if a valid Spoti
 Cover Art URL
 '''''''''''''
 
-The `fetchart` plugin can also use a flexible attribute field ``cover_art_url``
+The ``fetchart`` plugin can also use a flexible attribute field
-where you can manually specify the image URL to be used as cover art. Any custom
+``cover_art_url`` where you can manually specify the image URL to be used as
-plugin can use this field to provide the cover art and ``fetchart`` will use it
+cover art. Any custom plugin can use this field to provide the cover art and
-as a source.
+``fetchart`` will use it as a source.
 
 .. _cover-art-archive-maxwidth:
 
@@ -277,8 +279,8 @@ Cover Art Archive Pre-sized Thumbnails
 --------------------------------------
 
 The CAA provides pre-sized thumbnails of width 250, 500, and 1200 pixels. If you
-set the `maxwidth` option to one of these values, the corresponding image will
+set the ``maxwidth`` option to one of these values, the corresponding image will
-be downloaded, saving `beets` the need to scale down the image. It can also
+be downloaded, saving ``beets`` the need to scale down the image. It can also
 speed up the downloading process, as some cover arts can sometimes be very
 large.
 

docs/plugins/fish.rst

@@ -41,13 +41,13 @@ commands and option flags.
 
 If you want generated completions to also contain album/track field *values* for
 the items in your library, you can use the ``-e`` or ``--extravalues`` option.
-For example: ``beet fish -e genre`` or ``beet fish -e genre -e albumartist``
+For example: ``beet fish -e genre`` or ``beet fish -e genre -e albumartist`` In
-In the latter case, subsequently typing ``beet list genre: <TAB>`` will display
+the latter case, subsequently typing ``beet list genre: <TAB>`` will display a
-a list of all the genres in your library and ``beet list albumartist: <TAB>``
+list of all the genres in your library and ``beet list albumartist: <TAB>`` will
-will show a list of the album artists in your library. Keep in mind that all of
+show a list of the album artists in your library. Keep in mind that all of these
-these values will be put into the generated completions file, so use this option
+values will be put into the generated completions file, so use this option with
-with care when specified fields contain a large number of values. Libraries with,
+care when specified fields contain a large number of values. Libraries with, for
-for example, very large numbers of genres/artists may result in higher memory
+example, very large numbers of genres/artists may result in higher memory
 utilization, completion latency, et cetera. This option is not meant to replace
 database queries altogether.
 

docs/plugins/ftintitle.rst

@@ -24,8 +24,9 @@ file. The available options are:
 - **drop**: Remove featured artists entirely instead of adding them to the
   title field.
   Default: ``no``.
-- **format**: Defines the format for the featuring X  part of the new title field.
+- **format**: Defines the format for the featuring X  part of the new title
-  In this format the ``{0}`` is used to define where the featured artists are placed.
+  field. In this format the ``{0}`` is used to define where the featured
+  artists are placed.
   Default: ``feat. {0}``
 - **keep_in_artist**: Keep the featuring X part in the artist field. This can
   be useful if you still want to be able to search for features in the artist

docs/plugins/index.rst

@@ -13,7 +13,8 @@ Using Plugins
 -------------
 
 To use one of the plugins included with beets (see the rest of this page for a
-list), just use the ``plugins`` option in your :doc:`config.yaml </reference/config>` file:
+list), just use the ``plugins`` option in your :doc:`config.yaml
+</reference/config>` file:
 
 .. code-block:: sh
 
@@ -23,7 +24,8 @@ The value for ``plugins`` can be a space-separated list of plugin names or a
 YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
 by typing ``beet version``.
 
-Each plugin has its own set of options that can be defined in a section bearing its name:
+Each plugin has its own set of options that can be defined in a section bearing
+its name:
 
 .. code-block:: yaml
 
@@ -176,7 +178,8 @@ Metadata
 --------
 
 :doc:`absubmit <absubmit>`
-   Analyse audio with the `streaming_extractor_music`_ program and submit the metadata to an AcousticBrainz server
+   Analyse audio with the `streaming_extractor_music`_ program and submit the
+   metadata to an AcousticBrainz server
 
 :doc:`acousticbrainz <acousticbrainz>`
    Fetch various AcousticBrainz metadata
@@ -209,7 +212,7 @@ Metadata
 
 :doc:`importadded <importadded>`
    Use file modification times for guessing the value for
-   the `added` field in the database.
+   the ``added`` field in the database.
 
 :doc:`lastgenre <lastgenre>`
    Fetch genres based on Last.fm tags.
@@ -415,9 +418,8 @@ are two options for installation:
 * Make sure it's in the Python path (known as ``sys.path`` to developers). This
   just means the plugin has to be installed on your system (e.g., with a
   ``setup.py`` script or a command like ``pip`` or ``easy_install``).
-
+* Set the ``pluginpath`` config variable to point to the directory containing
-* Set the ``pluginpath`` config variable to point to the directory containing the
+  the plugin. (See :doc:`/reference/config`.)
-  plugin. (See :doc:`/reference/config`.)
 
 Once the plugin is installed, enable it by placing its name on the ``plugins``
 line in your config file.
@@ -449,7 +451,8 @@ Here are a few of the plugins written by the beets community:
    search for their metadata.
 
 `beetcamp`_
-   Enables **bandcamp.com** autotagger with a fairly extensive amount of metadata.
+   Enables **bandcamp.com** autotagger with a fairly extensive amount of
+   metadata.
 
 `beetstream`_
    Server implementation of the `Subsonic API`_ specification, serving the
@@ -481,7 +484,7 @@ Here are a few of the plugins written by the beets community:
 
 `beets-filetote`_
    Helps bring non-music extra files, attachments, and artifacts during
-   imports and CLI file manipulation actions (`beet move`, etc.).
+   imports and CLI file manipulation actions (``beet move``, etc.).
 
 `beets-follow`_
    Lets you check for new albums from artists you like.
@@ -507,13 +510,15 @@ Here are a few of the plugins written by the beets community:
    Adds JioSaavn.com as a tagger data source.
 
 `beets-more`_
-   Finds versions of indexed releases with more tracks, like deluxe and anniversary editions.
+   Finds versions of indexed releases with more tracks, like deluxe and
+   anniversary editions.
 
 `beets-mosaic`_
    Generates a montage of a mosaic from cover art.
 
 `beets-mpd-utils`_
-    Plugins to interface with `MPD`_. Comes with ``mpd_tracker`` (track play/skip counts from MPD) and  ``mpd_dj`` (auto-add songs to your queue.)
+    Plugins to interface with `MPD`_. Comes with ``mpd_tracker`` (track
+    play/skip counts from MPD) and  ``mpd_dj`` (auto-add songs to your queue.)
 
 `beets-noimport`_
    Adds and removes directories from the incremental import skip list.
@@ -523,7 +528,9 @@ Here are a few of the plugins written by the beets community:
    to improve autotagger results.
 
 `beets-plexsync`_
-   Allows you to sync your Plex library with your beets library, create smart playlists in Plex, and import online playlists (from services like Spotify) into Plex.
+   Allows you to sync your Plex library with your beets library, create smart
+   playlists in Plex, and import online playlists (from services like Spotify)
+   into Plex.
 
 `beets-setlister`_
    Generate playlists from the setlists of a given artist.

docs/plugins/inline.rst

@@ -6,14 +6,13 @@ it, you can define template fields in your beets configuration file and refer
 to them from your template strings in the ``paths:`` section (see
 :doc:`/reference/config/`).
 
-To use the ``inline`` plugin, enable it in your configuration
+To use the ``inline`` plugin, enable it in your configuration (see
-(see :ref:`using-plugins`).
+:ref:`using-plugins`). Then, make a ``item_fields:`` block in your config file.
-Then, make a ``item_fields:`` block in your config file. Under this key, every line defines a
+Under this key, every line defines a new template field; the key is the name of
-new template field; the key is the name of the field (you'll use the name to
+the field (you'll use the name to refer to the field in your templates) and the
-refer to the field in your templates) and the value is a Python expression or
+value is a Python expression or function body. The Python code has all of a
-function body. The Python code has all of a track's fields in scope, so you can
+track's fields in scope, so you can refer to any normal attributes (such as
-refer to any normal attributes (such as ``artist`` or ``title``) as Python
+``artist`` or ``title``) as Python variables.
-variables.
 
 Here are a couple of examples of expressions::
 

docs/plugins/ipfs.rst

@@ -71,4 +71,7 @@ The ipfs plugin will automatically add imported albums to ipfs and add those
 hashes to the database. This can be turned off by setting the ``auto`` option
 in the ``ipfs:`` section of the config to ``no``.
 
-If the setting ``nocopy`` is true (defaults false) then the plugin will pass the ``--nocopy`` option when adding things to ipfs. If the filestore option of ipfs is enabled this will mean files are neither removed from beets nor copied somewhere else.
+If the setting ``nocopy`` is true (defaults false) then the plugin will pass the
+``--nocopy`` option when adding things to ipfs. If the filestore option of ipfs
+is enabled this will mean files are neither removed from beets nor copied
+somewhere else.

docs/plugins/keyfinder.rst

@@ -1,9 +1,9 @@
 Key Finder Plugin
 =================
 
-The `keyfinder` plugin uses either the `KeyFinder`_ or `keyfinder-cli`_
+The ``keyfinder`` plugin uses either the `KeyFinder`_ or `keyfinder-cli`_
 program to  detect the musical key of a track from its audio data and store
-it in the `initial_key` field of your database.  It does so
+it in the ``initial_key`` field of your database.  It does so
 automatically when importing music or through the ``beet keyfinder
 [QUERY]`` command.
 
@@ -28,7 +28,7 @@ configuration file. The available options are:
   If using `keyfinder-cli`_, the binary must be named ``keyfinder-cli``.
   Default: ``KeyFinder`` (i.e., search for the program in your ``$PATH``)..
 - **overwrite**: Calculate a key even for files that already have an
-  `initial_key` value.
+  ``initial_key`` value.
   Default: ``no``.
 
 .. _KeyFinder: http://www.ibrahimshaath.co.uk/keyfinder/

docs/plugins/kodiupdate.rst

@@ -38,7 +38,8 @@ To use the ``kodiupdate`` plugin, first enable it in your configuration (see
 
 You'll also need to enable JSON-RPC in Kodi.
 
-In Kodi's interface, navigate to System/Settings/Network/Services and choose "Allow control of Kodi via HTTP."
+In Kodi's interface, navigate to System/Settings/Network/Services and choose
+"Allow control of Kodi via HTTP."
 
 With that all in place, you'll see beets send the "update" command to your Kodi
 host every time you change your beets library.

docs/plugins/lastgenre.rst

@@ -1,9 +1,8 @@
 LastGenre Plugin
 ================
 
-
+The ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as
-The ``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres
+genres to your albums and items.
-to your albums and items.
 
 .. _Last.fm: https://last.fm/
 
@@ -39,8 +38,8 @@ Canonicalization
 
 The plugin can also *canonicalize* genres, meaning that more obscure genres can
 be turned into coarser-grained ones that are present in the whitelist. This
-works using a `tree of nested genre names`_, represented using `YAML`_, where the
+works using a `tree of nested genre names`_, represented using `YAML`_, where
-leaves of the tree represent the most specific genres.
+the leaves of the tree represent the most specific genres.
 
 The most common way to use this would be with a custom whitelist containing only
 a desired subset of genres. Consider for a example this minimal whitelist::
@@ -154,8 +153,8 @@ make sure any existing genres remain, set ``whitelist: no``).
     keep_existing: yes
 
 .. attention::
-    If ``force`` is disabled the ``keep_existing`` option is simply ignored (since ``force:
+    If ``force`` is disabled the ``keep_existing`` option is simply ignored
-    no`` means `not touching` existing tags anyway).
+    (since ``force: no`` means ``not touching`` existing tags anyway).
 
 
 
@@ -173,9 +172,9 @@ configuration file. The available options are:
   Default: ``no`` (disabled).
 - **count**: Number of genres to fetch.
   Default: 1
-- **fallback**: A string to use as a fallback genre when no genre is found `or`
+- **fallback**: A string to use as a fallback genre when no genre is found
-  the original genre is not desired to be kept (``keep_existing: no``). You can
+  ``or`` the original genre is not desired to be kept (``keep_existing: no``).
-  use the empty string ``''`` to reset the genre.
+  You can use the empty string ``''`` to reset the genre.
   Default: None.
 - **force**: By default, lastgenre will fetch new genres for empty tags only,
   enable this option to always try to fetch new last.fm genres. Enable the
@@ -214,9 +213,9 @@ configuration file. The available options are:
 Running Manually
 ----------------
 
-In addition to running automatically on import, the plugin can also be run manually
+In addition to running automatically on import, the plugin can also be run
-from the command line. Use the command ``beet lastgenre [QUERY]`` to fetch
+manually from the command line. Use the command ``beet lastgenre [QUERY]`` to
-genres for albums or items matching a certain query.
+fetch genres for albums or items matching a certain query.
 
 By default, ``beet lastgenre`` matches albums. To match
 individual tracks or singletons, use the ``-A`` switch:

docs/plugins/limit.rst

@@ -1,32 +1,32 @@
 Limit Query Plugin
 ==================
 
-``limit`` is a plugin to limit a query to the first or last set of 
+``limit`` is a plugin to limit a query to the first or last set of
-results. We also provide a query prefix ``'<n'`` to inline the same 
+results. We also provide a query prefix ``'<n'`` to inline the same
 behavior in the ``list`` command. They are analogous to piping results:
 
     $ beet [list|ls] [QUERY] | [head|tail] -n n
 
 There are two provided interfaces:
 
-1. ``beet lslimit [--head n | --tail n] [QUERY]`` returns the head or 
+1. ``beet lslimit [--head n | --tail n] [QUERY]`` returns the head or
 tail of a query
 
 2. ``beet [list|ls] [QUERY] '<n'`` returns the head of a query
 
-There are two differences in behavior: 
+There are two differences in behavior:
 
 1. The query prefix does not support tail.
 
-2. The query prefix could appear anywhere in the query but will only 
+2. The query prefix could appear anywhere in the query but will only
-have the same behavior as the ``lslimit`` command and piping to ``head`` 
+have the same behavior as the ``lslimit`` command and piping to ``head``
 when it appears last.
 
-Performance for the query previx is much worse due to the current  
+Performance for the query previx is much worse due to the current
-singleton-based implementation. 
+singleton-based implementation.
 
-So why does the query prefix exist? Because it composes with any other 
+So why does the query prefix exist? Because it composes with any other
-query-based API or plugin (see :doc:`/reference/query`). For example, 
+query-based API or plugin (see :doc:`/reference/query`). For example,
 you can use the query prefix in ``smartplaylist``
 (see :doc:`/plugins/smartplaylist`) to limit the number of tracks in a smart
 playlist for applications like most played and recently added.
@@ -42,17 +42,23 @@ Examples
 
 First 10 tracks
 
-    $ beet ls | head -n 10
+.. code-block:: sh
-    $ beet lslimit --head 10
+
-    $ beet ls '<10'
+   $ beet ls | head -n 10
+   $ beet lslimit --head 10
+   $ beet ls '<10'
 
 Last 10 tracks
 
+.. code-block:: sh
+
     $ beet ls | tail -n 10
     $ beet lslimit --tail 10
 
 100 mostly recently released tracks
 
+.. code-block:: sh
+
     $ beet lslimit --head 100 year- month- day-
     $ beet ls year- month- day- '<100'
     $ beet lslimit --tail 100 year+ month+ day+

docs/plugins/listenbrainz.rst

@@ -3,19 +3,22 @@
 ListenBrainz Plugin
 ===================
 
-The ListenBrainz plugin for beets allows you to interact with the ListenBrainz service.
+The ListenBrainz plugin for beets allows you to interact with the ListenBrainz
+service.
 
 Installation
 ------------
 
-To enable the ListenBrainz plugin, add the following to your beets configuration file (`config.yaml`_):
+To enable the ListenBrainz plugin, add the following to your beets
+configuration file (`config.yaml`_):
 
 .. code-block:: yaml
 
    plugins:
        - listenbrainz
 
-You can then configure the plugin by providing your Listenbrainz token (see intructions `here`_) and username::
+You can then configure the plugin by providing your Listenbrainz token (see
+intructions `here`_) and username::
 
     listenbrainz:
         token: TOKEN
@@ -25,7 +28,8 @@ You can then configure the plugin by providing your Listenbrainz token (see intr
 Usage
 -----
 
-Once the plugin is enabled, you can import the listening history using the `lbimport` command in beets.
+Once the plugin is enabled, you can import the listening history using the
+``lbimport`` command in beets.
 
 
 .. _here: https://listenbrainz.readthedocs.io/en/latest/users/api/index.html#get-the-user-token

docs/plugins/loadext.rst

@@ -49,5 +49,5 @@ specifics may vary from system to system):
     $ wget https://sqlite.org/2019/sqlite-src-3280000.zip
     $ unzip sqlite-src-3280000.zip
     $ cd sqlite-src-3280000/ext/icu
-    $ gcc -shared -fPIC icu.c `icu-config --ldflags` -o libicu.so
+    $ gcc -shared -fPIC icu.c $(icu-config --ldflags) -o libicu.so
     $ cp libicu.so ~/.config/beets

docs/plugins/mbsubmit.rst

@@ -44,7 +44,8 @@ choice is demonstrated::
     [U]se as-is, as Tracks, Group albums, Skip, Enter search, enter Id, aBort,
     Print tracks?
 
-You can also run ``beet mbsubmit QUERY`` to print the track information for any album::
+You can also run ``beet mbsubmit QUERY`` to print the track information for any
+album::
 
     $ beet mbsubmit album:"An Obscure Album"
     01. An Obscure Track - An Obscure Artist (3:37)

docs/plugins/mpdstats.rst

@@ -9,9 +9,9 @@ habits from `MPD`_.  It collects the following information about tracks:
 * ``last_played``:  UNIX timestamp when you last played this track.
 * ``rating``: A rating based on ``play_count`` and ``skip_count``.
 
-To gather these statistics it runs as an MPD client and watches the current state
+To gather these statistics it runs as an MPD client and watches the current
-of MPD. This means that ``mpdstats`` needs to be running continuously for it to
+state of MPD. This means that ``mpdstats`` needs to be running continuously for
-work.
+it to work.
 
 .. _MPD: https://www.musicpd.org/
 
@@ -50,16 +50,16 @@ configuration file. The available options are:
 - **music_directory**: If your MPD library is at a different location from the
   beets library (e.g., because one is mounted on a NFS share), specify the path
   here.
-- **strip_path**: If your MPD library contains local path, specify the part to remove
+- **strip_path**: If your MPD library contains local path, specify the part to
-  here. Combining this with **music_directory** you can mangle MPD path to match the 
+  remove here. Combining this with **music_directory** you can mangle MPD path
-  beets library one.
+  to match the beets library one.
   Default: The beets library directory.
 - **rating**: Enable rating updates.
   Default: ``yes``.
 - **rating_mix**: Tune the way rating is calculated (see below).
   Default: 0.75.
-- **played_ratio_threshold**: If a song was played for less than this percentage
+- **played_ratio_threshold**: If a song was played for less than this
-  of its duration it will be considered a skip.
+  percentage of its duration it will be considered a skip.
   Default: 0.85
 
 A Word on Ratings

docs/plugins/mpdupdate.rst

@@ -20,9 +20,9 @@ which looks like this::
 With that all in place, you'll see beets send the "update" command to your MPD
 server every time you change your beets library.
 
-If you want to communicate with MPD over a Unix domain socket instead over
+If you want to communicate with MPD over a Unix domain socket instead over TCP,
-TCP, just give the path to the socket in the filesystem for the ``host``
+just give the path to the socket in the filesystem for the ``host`` setting.
-setting. (Any ``host`` value starting with a slash or a tilde is interpreted as a domain
+(Any ``host`` value starting with a slash or a tilde is interpreted as a domain
 socket.)
 
 Configuration
@@ -31,7 +31,8 @@ Configuration
 The available options under the ``mpd:`` section are:
 
 - **host**: The MPD server name.
-  Default: The ``$MPD_HOST`` environment variable if set, falling back to ``localhost`` otherwise.
+  Default: The ``$MPD_HOST`` environment variable if set, falling back to
+  ``localhost`` otherwise.
 - **port**: The MPD server port.
   Default: The ``$MPD_PORT`` environment variable if set, falling back to 6600
   otherwise.

docs/plugins/musicbrainz.rst

@@ -51,15 +51,16 @@ under a ``musicbrainz:`` header, like so
         ratelimit: 100
 
 The ``host`` key, of course, controls the Web server hostname (and port,
-optionally) that will be contacted by beets (default: musicbrainz.org).
+optionally) that will be contacted by beets (default: musicbrainz.org). The
-The ``https`` key makes the client use HTTPS instead of HTTP. This setting applies
+``https`` key makes the client use HTTPS instead of HTTP. This setting applies
-only to custom servers. The official MusicBrainz server always uses HTTPS. (Default: no.)
+only to custom servers. The official MusicBrainz server always uses HTTPS.
-The server must have search indices enabled (see `Building search indexes`_).
+(Default: no.) The server must have search indices enabled (see `Building search
+indexes`_).
 
-The ``ratelimit`` option, an integer, controls the number of Web service requests
+The ``ratelimit`` option, an integer, controls the number of Web service
-per second (default: 1). **Do not change the rate limit setting** if you're
+requests per second (default: 1). **Do not change the rate limit setting** if
-using the main MusicBrainz server---on this public server, you're `limited`_
+you're using the main MusicBrainz server---on this public server, you're
-to one request per second.
+`limited`_ to one request per second.
 
 .. _your own MusicBrainz database: https://musicbrainz.org/doc/MusicBrainz_Server/Setup
 .. _main server: https://musicbrainz.org/
@@ -72,11 +73,11 @@ enabled
 ~~~~~~~
 
 .. deprecated:: 2.3
-  Add `musicbrainz` to the `plugins` list instead.
+  Add ``musicbrainz`` to the ``plugins`` list instead.
 
-This option allows you to disable using MusicBrainz as a metadata source. This applies
+This option allows you to disable using MusicBrainz as a metadata source. This
-if you use plugins that fetch data from alternative sources and should make the import
+applies if you use plugins that fetch data from alternative sources and should
-process quicker.
+make the import process quicker.
 
 Default: ``yes``.
 

docs/plugins/parentwork.rst

@@ -37,7 +37,7 @@ This plugin adds seven tags:
   that has a composition date. Format: yyyy-mm-dd.
 - **parentwork_workid_current**: The MusicBrainz id of the work as it was when
   the parentwork was retrieved. This tag exists only for internal bookkeeping,
-  to keep track of recordings whose works have changed. 
+  to keep track of recordings whose works have changed.
 - **parentwork_date**: The composition date of the parent work.
 
 To use the ``parentwork`` plugin, enable it in your configuration (see
@@ -50,7 +50,7 @@ To configure the plugin, make a ``parentwork:`` section in your
 configuration file. The available options are:
 
 - **force**: As a default, ``parentwork`` only fetches work info for
-  recordings that do not already have a ``parentwork`` tag or where 
+  recordings that do not already have a ``parentwork`` tag or where
   ``mb_workid`` differs from ``parentwork_workid_current``. If ``force``
   is enabled, it fetches it for all recordings.
   Default: ``no``

docs/plugins/permissions.rst

@@ -12,7 +12,8 @@ Configuration
 
 To configure the plugin, make an ``permissions:`` section in your configuration
 file. The ``file`` config value therein uses **octal modes** to specify the
-desired permissions. The default flags for files are octal 644 and 755 for directories.
+desired permissions. The default flags for files are octal 644 and 755 for
+directories.
 
 Here's an example::
 

docs/plugins/play.rst

@@ -33,8 +33,8 @@ Interactive Usage
 -----------------
 
 The ``play`` plugin can also be invoked during an import. If enabled, the plugin
-adds a ``plaY`` option to the prompt, so pressing ``y`` will execute the configured
+adds a ``plaY`` option to the prompt, so pressing ``y`` will execute the
-command and play the items currently being imported.
+configured command and play the items currently being imported.
 
 Once the configured command exits, you will be returned to the import
 decision prompt.  If your player is configured to run in the background (in a
@@ -99,7 +99,7 @@ indicates that you need to insert extra arguments before specifying the
 playlist.
 
 The ``--yes`` (or ``-y``) flag to the ``play`` command will skip the warning
-message if you choose to play more items than the **warning_threshold** 
+message if you choose to play more items than the **warning_threshold**
 value usually allows.
 
 Note on the Leakage of the Generated Playlists
@@ -108,10 +108,10 @@ Note on the Leakage of the Generated Playlists
 Because the command that will open the generated ``.m3u`` files can be
 arbitrarily configured by the user, beets won't try to delete those files. For
 this reason, using this plugin will leave one or several playlist(s) in the
-directory selected to create temporary files (Most likely ``/tmp/`` on Unix-like
+directory selected to create temporary files (Most likely ``/tmp/`` on
-systems. See `tempfile.tempdir`_ in the Python docs.). Leaking those playlists until
+Unix-like systems. See `tempfile.tempdir`_ in the Python docs.). Leaking those
-they are externally wiped could be an issue for privacy or storage reasons. If
+playlists until they are externally wiped could be an issue for privacy or
-this is the case for you, you might want to use the ``raw`` config option
+storage reasons. If this is the case for you, you might want to use the ``raw``
-described above.
+config option described above.
 
 .. _tempfile.tempdir: https://docs.python.org/2/library/tempfile.html#tempfile.tempdir

docs/plugins/plexupdate.rst

@@ -10,9 +10,9 @@ Firstly, install ``beets`` with ``plexupdate`` extra
 
     pip install "beets[plexupdate]"
 
-Then, enable ``plexupdate`` plugin it in your configuration (see :ref:`using-plugins`).
+Then, enable ``plexupdate`` plugin it in your configuration (see
-Optionally, configure the specifics of your Plex server. You can do this using
+:ref:`using-plugins`). Optionally, configure the specifics of your Plex server.
-a ``plex:`` section in your ``config.yaml``:
+You can do this using a ``plex:`` section in your ``config.yaml``:
 
 .. code-block:: yaml
 
@@ -21,7 +21,8 @@ a ``plex:`` section in your ``config.yaml``:
        port: 32400
        token: "TOKEN"
 
-The ``token`` key is optional: you'll need to use it when in a Plex Home (see Plex's own `documentation about tokens`_).
+The ``token`` key is optional: you'll need to use it when in a Plex Home (see
+Plex's own `documentation about tokens`_).
 
 With that all in place, you'll see beets send the "update" command to your Plex
 server every time you change your beets library.
@@ -44,5 +45,6 @@ The available options under the ``plex:`` section are:
   Default: ``Music``
 - **secure**: Use secure connections to the Plex server.
   Default: ``False``
-- **ignore_cert_errors**: Ignore TLS certificate errors when using secure connections.
+- **ignore_cert_errors**: Ignore TLS certificate errors when using secure
+  connections.
   Default: ``False``

docs/plugins/replace.rst

@@ -13,5 +13,5 @@ and then type::
 The plugin will show you a list of files for you to pick from, and then
 ask for confirmation.
 
-Consider using the `replaygain` command from the
+Consider using the ``replaygain`` command from the
 :doc:`/plugins/replaygain` plugin, if you usually use it during imports.

docs/plugins/replaygain.rst

@@ -28,7 +28,8 @@ GStreamer
 
 To use `GStreamer`_ for ReplayGain analysis, you will of course need to
 install GStreamer and plugins for compatibility with your audio files.
-You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a. ``python-gi``).
+You will need at least GStreamer 1.0 and `PyGObject 3.x`_ (a.k.a.
+``python-gi``).
 
 .. _PyGObject 3.x: https://pygobject.readthedocs.io/en/latest/
 .. _GStreamer: https://gstreamer.freedesktop.org/
@@ -108,17 +109,16 @@ configuration file. The available options are:
 
 - **auto**: Enable ReplayGain analysis during import.
   Default: ``yes``.
-- **threads**: The number of parallel threads to run the analysis in. Overridden
+- **threads**: The number of parallel threads to run the analysis in.
-  by ``--threads`` at the command line.
+  Overridden by ``--threads`` at the command line.
   Default: # of logical CPU cores
-- **parallel_on_import**: Whether to enable parallel analysis during import.
+- **parallel_on_import**: Whether to enable parallel analysis during import. As
-  As of now this ReplayGain data is not written to files properly, so this option
+  of now this ReplayGain data is not written to files properly, so this option
-  is disabled by default.
+  is disabled by default. If you wish to enable it, remember to run ``beet
-  If you wish to enable it, remember to run ``beet write`` after importing to
+  write`` after importing to actually write to the imported files.
-  actually write to the imported files.
   Default: ``no``
-- **backend**: The analysis backend; either ``gstreamer``, ``command``, ``audiotools``
+- **backend**: The analysis backend; either ``gstreamer``, ``command``,
-  or ``ffmpeg``.
+  ``audiotools`` or ``ffmpeg``.
   Default: ``command``.
 - **overwrite**: On import, re-analyze files that already have ReplayGain tags.
   Note that, for historical reasons, the name of this option is somewhat
@@ -136,7 +136,8 @@ configuration file. The available options are:
   integer values instead of the common ``REPLAYGAIN_`` tags with floating point
   values. Requires the "ffmpeg" backend.
   Default: ``Opus``.
-- **per_disc**: Calculate album ReplayGain on disc level instead of album level.
+- **per_disc**: Calculate album ReplayGain on disc level instead of album
+  level.
   Default: ``no``
 
 These options only work with the "command" backend:
@@ -171,7 +172,8 @@ whether ReplayGain tags are written into the music files, or stored in the
 beets database only (the default is to use :ref:`the importer's configuration
 <config-import-write>`).
 
-To execute with a different number of threads, call ``beet replaygain --threads N``::
+To execute with a different number of threads, call ``beet replaygain --threads
+N``::
 
     $ beet replaygain --threads N [-Waf] [QUERY]
 

docs/plugins/spotify.rst

@@ -16,7 +16,8 @@ Why Use This Plugin?
 --------------------
 
 * You're a Beets user and Spotify user already.
-* You have playlists or albums you'd like to make available in Spotify from Beets without having to search for each artist/album/track.
+* You have playlists or albums you'd like to make available in Spotify from
+  Beets without having to search for each artist/album/track.
 * You want to check which tracks in your library are available on Spotify.
 * You want to autotag music with metadata from the Spotify API.
 * You want to obtain track popularity and audio features (e.g., danceability)
@@ -53,7 +54,8 @@ prompt during import::
 Configuration
 -------------
 
-This plugin can be configured like other metadata source plugins as described in :ref:`metadata-source-plugin-configuration`. In addition, the following
+This plugin can be configured like other metadata source plugins as described in
+:ref:`metadata-source-plugin-configuration`. In addition, the following
 configuration options are provided.
 
 The default options should work as-is, but there are some options you can put
@@ -83,11 +85,11 @@ in config.yaml under the ``spotify:`` section:
   track/album/artist fields before sending them to Spotify.  Can be useful for
   changing certain abbreviations, like ft. -> feat.  See the examples below.
   Default: None.
-- **search_query_ascii**: If set to ``yes``, the search query will be converted to
+- **search_query_ascii**: If set to ``yes``, the search query will be converted
-  ASCII before being sent to Spotify. Converting searches to ASCII can
+  to ASCII before being sent to Spotify. Converting searches to ASCII can
-  enhance search results in some cases, but in general, it is not recommended. 
+  enhance search results in some cases, but in general, it is not recommended.
-  For instance `artist:deadmau5 album:4×4` will be converted to 
+  For instance ``artist:deadmau5 album:4×4`` will be converted to
-  `artist:deadmau5 album:4x4` (notice `×!=x`).
+  ``artist:deadmau5 album:4x4`` (notice ``×!=x``).
   Default: ``no``.
 
 

docs/plugins/subsonicplaylist.rst

@@ -1,14 +1,15 @@
 Subsonic Playlist Plugin
 ========================
 
-The ``subsonicplaylist`` plugin allows to import playlists from a subsonic server.
+The ``subsonicplaylist`` plugin allows to import playlists from a subsonic
-This is done by retrieving the track info from the subsonic server, searching
+server. This is done by retrieving the track info from the subsonic server,
-for them in the beets library, and adding the playlist names to the
+searching for them in the beets library, and adding the playlist names to the
-`subsonic_playlist` tag of the found items. The content of the tag has the format:
+``subsonic_playlist`` tag of the found items. The content of the tag has the
+format:
 
     subsonic_playlist: ";first playlist;second playlist;"
 
-To get all items in a playlist use the query `;playlist name;`.
+To get all items in a playlist use the query ``;playlist name;``.
 
 Command Line Usage
 ------------------
@@ -22,15 +23,18 @@ Next, configure the plugin to connect to your Subsonic server, like this::
         username: someUser
         password: somePassword
 
-After this you can import your playlists by invoking the `subsonicplaylist` command.
+After this you can import your playlists by invoking the ``subsonicplaylist``
+command.
 
 By default only the tags of the items found for playlists will be updated.
 This means that, if one imported a playlist, then delete one song from it and
 imported the playlist again, the deleted song will still have the playlist set
-in its `subsonic_playlist` tag. To solve this problem one can use the `-d/--delete`
+in its ``subsonic_playlist`` tag. To solve this problem one can use the
-flag. This resets all `subsonic_playlist` tag before importing playlists.
+``-d/--delete`` flag. This resets all ``subsonic_playlist`` tag before importing
+playlists.
 
-Here's an example configuration with all the available options and their default values::
+Here's an example configuration with all the available options and their default
+values::
 
     subsonicplaylist:
         base_url: "https://your.subsonic.server"
@@ -40,4 +44,4 @@ Here's an example configuration with all the available options and their default
         username: ''
         password: ''
 
-The `base_url`, `username`, and `password` options are required.
+The ``base_url``, ``username``, and ``password`` options are required.

docs/plugins/substitute.rst

@@ -1,17 +1,18 @@
 Substitute Plugin
 =================
 
-The ``substitute`` plugin lets you easily substitute values in your templates and
+The ``substitute`` plugin lets you easily substitute values in your templates
-path formats. Specifically, it is intended to let you *canonicalize* names
+and path formats. Specifically, it is intended to let you *canonicalize* names
 such as artists: For example, perhaps you want albums from The Jimi Hendrix
 Experience to be sorted into the same folder as solo Hendrix albums.
 
 This plugin is intended as a replacement for the ``rewrite`` plugin. While
 the ``rewrite`` plugin modifies the metadata, this plugin does not.
 
-Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a ``substitute:`` section in your config file to contain your rules.
+Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a
-Each rule consists of a case-insensitive regular expression pattern, and a
+``substitute:`` section in your config file to contain your rules. Each rule
-replacement string. For example, you might use:
+consists of a case-insensitive regular expression pattern, and a replacement
+string. For example, you might use:
 
 .. code-block:: yaml
 
@@ -21,7 +22,7 @@ replacement string. For example, you might use:
 The replacement can be an expression utilising the matched regex, allowing us
 to create more general rules. Say for example, we want to sort all albums by
 multiple artists into the directory of the first artist. We can thus capture
-everything before the first ``,``, `` &`` or `` and``, and use this capture
+everything before the first ``,``, ``\ &`` or ``\ and``, and use this capture
 group in the output, discarding the rest of the string.
 
 .. code-block:: yaml
@@ -35,8 +36,8 @@ This would handle all the below cases in a single rule:
     | Neil Young & Crazy Horse -> Neil Young
     | James Yorkston, Nina Persson & The Second Hand Orchestra -> James Yorkston
 
-
+To apply the substitution, you have to call the function ``%substitute{}`` in
-To apply the substitution, you have to call the function ``%substitute{}`` in the paths section. For example:
+the paths section. For example:
 
 .. code-block:: yaml
 

docs/plugins/unimported.rst

@@ -1,15 +1,17 @@
 Unimported Plugin
 =================
 
-The ``unimported`` plugin allows one to list all files in the library folder which are not listed in the beets library database, including art files.
+The ``unimported`` plugin allows one to list all files in the library folder
+which are not listed in the beets library database, including art files.
 
 Command Line Usage
 ------------------
 
 To use the ``unimported`` plugin, enable it in your configuration (see
 :ref:`using-plugins`). Then use it by invoking the ``beet unimported`` command.
-The command will list all files in the library folder which are not imported. You can
+The command will list all files in the library folder which are not imported.
-exclude file extensions or entire subdirectories using the configuration file::
+You can exclude file extensions or entire subdirectories using the configuration
+file::
 
     unimported:
         ignore_extensions: jpg png

docs/plugins/web.rst

@@ -55,14 +55,16 @@ configuration file. The available options are:
   Default: 8337.
 - **cors**: The CORS allowed origin (see :ref:`web-cors`, below).
   Default: CORS is disabled.
-- **cors_supports_credentials**: Support credentials when using CORS (see :ref:`web-cors`, below).
+- **cors_supports_credentials**: Support credentials when using CORS (see
+  :ref:`web-cors`, below).
   Default: CORS_SUPPORTS_CREDENTIALS is disabled.
 - **reverse_proxy**: If true, enable reverse proxy support (see
   :ref:`reverse-proxy`, below).
   Default: false.
 - **include_paths**: If true, includes paths in item objects.
   Default: false.
-- **readonly**: If true, DELETE and PATCH operations are not allowed. Only GET is permitted.
+- **readonly**: If true, DELETE and PATCH operations are not allowed. Only GET
+  is permitted.
   Default: true.
 
 Implementation
@@ -184,16 +186,16 @@ code.
 ``DELETE /item/6``
 ++++++++++++++++++
 
-Removes the item with id *6* from the beets library. If the *?delete* query string is included,
+Removes the item with id *6* from the beets library. If the *?delete* query
-the matching file will be deleted from disk.
+string is included, the matching file will be deleted from disk.
 
 Only allowed if ``readonly`` configuration option is set to ``no``.
 
 ``PATCH /item/6``
 ++++++++++++++++++
 
-Updates the item with id *6* and write the changes to the music file. The body should be a JSON object
+Updates the item with id *6* and write the changes to the music file. The body
-containing the changes to the object.
+should be a JSON object containing the changes to the object.
 
 Returns the updated JSON representation. ::
 
@@ -210,11 +212,11 @@ Only allowed if ``readonly`` configuration option is set to ``no``.
 
 Response with a list of tracks with the ids *6*, *12* and *13*.  The format of
 the response is the same as for `GET /item/`_. It is *not guaranteed* that the
-response includes all the items requested. If a track is not found it is silently
+response includes all the items requested. If a track is not found it is
-dropped from the response.
+silently dropped from the response.
 
-This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on all
+This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on
-items of the list.
+all items of the list.
 
 ``GET /item/path/...``
 ++++++++++++++++++++++
@@ -244,8 +246,8 @@ Path elements are joined as parts of a query. For example,
 To specify literal path separators in a query, use a backslash instead of a
 slash.
 
-This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on all
+This endpoint also supports *DELETE* and *PATCH* methods as above, to operate on
-items returned by the query.
+all items returned by the query.
 
 ``GET /item/6/file``
 ++++++++++++++++++++
@@ -281,7 +283,8 @@ or ``/album/5,7``. In addition we can request the cover art of an album with
 ``GET /album/5/art``.
 You can also add the '?expand' flag to get the individual items of an album.
 
-``DELETE`` is only allowed if ``readonly`` configuration option is set to ``no``.
+``DELETE`` is only allowed if ``readonly`` configuration option is set to
+``no``.
 
 ``GET /stats``
 ++++++++++++++

docs/plugins/zero.rst

@@ -7,8 +7,10 @@ the plugin can strip useless comments like "ripped by MyGreatRipper."
 
 The plugin can work in one of two modes:
 
-* ``fields``: A blacklist, where you choose the tags you want to remove (used by default).
+* ``fields``: A blacklist, where you choose the tags you want to remove (used by
-* ``keep_fields``: A whitelist, where you instead specify the tags you want to keep.
+  default).
+* ``keep_fields``: A whitelist, where you instead specify the tags you want to
+  keep.
 
 To use the ``zero`` plugin, enable the plugin in your configuration
 (see :ref:`using-plugins`).
@@ -31,7 +33,8 @@ fields to nullify and the conditions for nullifying them:
 * To conditionally filter a field, use ``field: [regexp, regexp]`` to specify
   regular expressions.
 * By default this plugin only affects files' tags; the beets database is left
-  unchanged. To update the tags in the database, set the ``update_database`` option to true.
+  unchanged. To update the tags in the database, set the ``update_database``
+  option to true.
 
 For example::
 

docs/reference/cli.rst

@@ -65,9 +65,9 @@ Directories passed to the import command can contain either a single
 album or many, in which case the leaf directories will be considered
 albums (the latter case is true of typical Artist/Album organizations
 and many people's "downloads" folders). The path can also be a single
-song or an archive. Beets supports `zip` and `tar` archives out of the
+song or an archive. Beets supports ``zip`` and ``tar`` archives out of the
-box. To extract `rar` files, install the `rarfile`_ package and the
+box. To extract ``rar`` files, install the `rarfile`_ package and the
-`unrar` command. To extract `7z` files, install the `py7zr`_ package.
+``unrar`` command. To extract ``7z`` files, install the `py7zr`_ package.
 
 Optional command flags:
 
@@ -95,7 +95,7 @@ Optional command flags:
   normal autotagger mode would ask for confirmation, the quiet mode
   performs a fallback action that can be configured using the
   ``quiet_fallback`` configuration or ``--quiet-fallback`` CLI option.
-  By default it pessimistically ``skip``s the file.
+  By default it pessimistically skips the file.
   Alternatively, it can be used as is, by configuring ``asis``.
 
 * Speaking of resuming interrupted imports, the tagger will prompt you if it
@@ -116,7 +116,7 @@ Optional command flags:
   ``incremental`` configuration option.
 
 * If you don't want to record skipped files during an *incremental* import, use
-  the ``--incremental-skip-later`` flag which corresponds to the 
+  the ``--incremental-skip-later`` flag which corresponds to the
   ``incremental_skip_later`` configuration option.
   Setting the flag prevents beets from persisting skip decisions during a
   non-interactive import so that a user can make a decision regarding
@@ -157,9 +157,10 @@ Optional command flags:
   searching for other candidates by using the ``--search-id SEARCH_ID`` option.
   Multiple IDs can be specified by simply repeating the option several times.
 
-* You can supply ``--set field=value`` to assign `field` to `value` on import.
+* You can supply ``--set field=value`` to assign ``field`` to ``value`` on
-  Values support the same template syntax as beets'
+  import. Values support the same template syntax as beets' :doc:`path formats
-  :doc:`path formats <pathformat>`.
+  <pathformat>`.
+
   These assignments will merge with (and possibly override) the
   :ref:`set_fields` configuration dictionary. You can use the option multiple
   times on the command line, like so::
@@ -246,21 +247,22 @@ remove
 Remove music from your library.
 
 This command uses the same :doc:`query <query>` syntax as the ``list`` command.
-By default, it just removes entries from the library database; it doesn't
+By default, it just removes entries from the library database; it doesn't touch
-touch the files on disk. To actually delete the files, use the ``-d`` flag.
+the files on disk. To actually delete the files, use the ``-d`` flag. When the
-When the ``-a`` flag is given, the command operates on albums instead of
+``-a`` flag is given, the command operates on albums instead of individual
-individual tracks.
+tracks.
+
+When you run the ``remove`` command, it prints a list of all affected items in
+the library and asks for your permission before removing them. You can then
+choose to abort (type ``n``), confirm (``y``), or interactively choose some of
+the items (``s``). In the latter case, the command will prompt you for every
+matching item or album and invite you to type ``y`` to remove the item/album,
+``n`` to keep it or ``q`` to exit and only remove the items/albums selected up
+to this point.
 
-When you run the ``remove`` command, it prints a list of all
-affected items in the library and asks for your permission before removing
-them. You can then choose to abort (type `n`), confirm (`y`), or interactively
-choose some of the items (`s`). In the latter case, the command will prompt you
-for every matching item or album and invite you to type `y` to remove the
-item/album, `n` to keep it or `q` to exit and only remove the items/albums
-selected up to this point.
 This option lets you choose precisely which tracks/albums to remove without
-spending too much time to carefully craft a query.
+spending too much time to carefully craft a query. If you do not want to be
-If you do not want to be prompted at all, use the ``-f`` option.
+prompted at all, use the ``-f`` option.
 
 .. _modify-cmd:
 
@@ -299,18 +301,17 @@ prevent this behavior, use ``-I``/``--noinherit``.
 Items will automatically be moved around when necessary if they're in your
 library directory, but you can disable that with  ``-M``. Tags will be written
 to the files according to the settings you have for imports, but these can be
-overridden with ``-w`` (write tags, the default) and ``-W`` (don't write
+overridden with ``-w`` (write tags, the default) and ``-W`` (don't write tags).
-tags).
 
-When you run the ``modify`` command, it prints a list of all
+When you run the ``modify`` command, it prints a list of all affected items in
-affected items in the library and asks for your permission before making any
+the library and asks for your permission before making any changes. You can
-changes. You can then choose to abort the change (type `n`), confirm
+then choose to abort the change (type ``n``), confirm (``y``), or interactively
-(`y`), or interactively choose some of the items (`s`). In the latter case,
+choose some of the items (``s``). In the latter case, the command will prompt
-the command will prompt you for every matching item or album and invite you to
+you for every matching item or album and invite you to type ``y`` to apply the
-type `y` to apply the changes, `n` to discard them or `q` to exit and apply
+changes, ``n`` to discard them or ``q`` to exit and apply the selected changes.
-the selected changes. This option lets you choose precisely which data to
+This option lets you choose precisely which data to change without spending too
-change without spending too much time to carefully craft a query. To skip the
+much time to carefully craft a query. To skip the prompts entirely, use the
-prompts entirely, use the ``-y`` option.
+``-y`` option.
 
 .. _move-cmd:
 
@@ -357,10 +358,10 @@ This will show you all the proposed changes but won't actually change anything
 on disk.
 
 By default, all the changed metadata will be populated back to the database.
-If you only want certain fields to be written, specify them with the ```-F```
+If you only want certain fields to be written, specify them with the ``-F``
 flags (which can be used multiple times). Alternatively, specify fields to *not*
-write with ```-e``` flags (which can be used multiple times). For the list of 
+write with ``-e`` flags (which can be used multiple times). For the list of
-supported fields, please see ```beet fields```.
+supported fields, please see ``beet fields``.
 
 When an updated track is part of an album, the album-level fields of *all*
 tracks from the album are also updated. (Specifically, the command copies
@@ -382,19 +383,20 @@ write
 
 Write metadata from the database into files' tags.
 
-When you make changes to the metadata stored in beets' library database
+When you make changes to the metadata stored in beets' library database (during
-(during import or with the :ref:`modify-cmd` command, for example), you often
+import or with the :ref:`modify-cmd` command, for example), you often have the
-have the option of storing changes only in the database, leaving your files
+option of storing changes only in the database, leaving your files untouched.
-untouched. The ``write`` command lets you later change your mind and write the
+The ``write`` command lets you later change your mind and write the contents of
-contents of the database into the files. By default, this writes the changes only if there is a difference between the database and the tags in the file.
+the database into the files. By default, this writes the changes only if there
+is a difference between the database and the tags in the file.
 
 You can think of this command as the opposite of :ref:`update-cmd`.
 
 The ``-p`` option previews metadata changes without actually applying them.
 
-The ``-f`` option forces a write to the file, even if the file tags match the database. This is useful for making sure that enabled plugins that run on write (e.g., the Scrub and Zero plugins) are run on the file.
+The ``-f`` option forces a write to the file, even if the file tags match the
-
+database. This is useful for making sure that enabled plugins that run on write
-
+(e.g., the Scrub and Zero plugins) are run on the file.
 
 .. _stats-cmd:
 
@@ -469,12 +471,12 @@ import ...``.
   in this config file will override the corresponding settings in your base
   configuration.
 * ``-p plugins``: specify a comma-separated list of plugins to enable. If
-  specified, the plugin list in your configuration is ignored. The long form
+  specified, the plugin list in your configuration is ignored. The long form of
-  of this argument also allows specifying no plugins, effectively disabling
+  this argument also allows specifying no plugins, effectively disabling all
-  all plugins: ``--plugins=``.
+  plugins: ``--plugins=``.
 * ``-P plugins``: specify a comma-separated list of plugins to disable in a
-  specific beets run. This will overwrite ``-p`` if used with it. To disable all plugins, use
+  specific beets run. This will overwrite ``-p`` if used with it. To disable
-  ``--plugins=`` instead.
+  all plugins, use ``--plugins=`` instead.
 
 Beets also uses the ``BEETSDIR`` environment variable to look for
 configuration and data.
@@ -522,7 +524,7 @@ zsh
 ```
 
 If you use zsh, take a look at the included `completion script`_. The script
-should be placed in a directory that is part of your ``fpath``, and `not`
+should be placed in a directory that is part of your ``fpath``, and ``not``
 sourced in your ``.zshrc``. Running ``echo $fpath`` will give you a list of
 valid directories.
 

docs/reference/config.rst

@@ -75,11 +75,11 @@ Filenames are relative to the directory containing ``config.yaml``.
 pluginpath
 ~~~~~~~~~~
 
-Directories to search for plugins.  Each Python file or directory in a plugin
+Directories to search for plugins. Each Python file or directory in a plugin
 path represents a plugin and should define a subclass of :class:`BeetsPlugin`.
-A plugin can then be loaded by adding the filename to the `plugins` configuration.
+A plugin can then be loaded by adding the filename to the ``plugins``
-The plugin path can either be a single string or a list of strings---so, if you
+configuration. The plugin path can either be a single string or a list of
-have multiple paths, format them as a YAML list like so::
+strings---so, if you have multiple paths, format them as a YAML list like so::
 
     pluginpath:
         - /path/one
@@ -186,8 +186,8 @@ take place before applying the :ref:`replace` configuration and are roughly
 equivalent to wrapping all your path templates in the ``%asciify{}``
 :ref:`template function <template-functions>`.
 
-This uses the `unidecode module`_ which is language agnostic, so some 
+This uses the `unidecode module`_ which is language agnostic, so some
-characters may be transliterated from a different language than expected. 
+characters may be transliterated from a different language than expected.
 For example, Japanese kanji will usually use their Chinese readings.
 
 Default: ``no``.
@@ -228,7 +228,7 @@ command and other commands that need to print out items. Defaults to
 ``$artist - $album - $title``. The ``-f`` command-line option overrides
 this setting.
 
-It used to be named `list_format_item`.
+It used to be named ``list_format_item``.
 
 .. _list_format_album:
 .. _format_album:
@@ -240,7 +240,7 @@ Format to use when listing *albums* with :ref:`list-cmd` and other
 commands. Defaults to ``$albumartist - $album``. The ``-f`` command-line
 option overrides this setting.
 
-It used to be named `list_format_album`.
+It used to be named ``list_format_album``.
 
 .. _sort_item:
 
@@ -283,11 +283,12 @@ That is, if this option is turned on, then ``year`` will always equal
 overwrite_null
 ~~~~~~~~~~~~~~
 
-This confusingly-named option indicates which fields have meaningful `null` values.  If
+This confusingly-named option indicates which fields have meaningful ``null``
-an album or track field is in the corresponding list, then an existing value for this
+values. If an album or track field is in the corresponding list, then an
-field in an item in the database can be overwritten with `null`.  By default, however,
+existing value for this field in an item in the database can be overwritten with
-`null` is interpreted as information about the field being unavailable, so it would not
+``null``. By default, however, ``null`` is interpreted as information about the
-overwrite existing values.  For example::
+field being unavailable, so it would not overwrite existing values. For
+example::
 
     overwrite_null:
         album: ["albumid"]
@@ -382,7 +383,7 @@ clutter
 
 When beets imports all the files in a directory, it tries to remove the
 directory if it's empty. A directory is considered empty if it only contains
-files whose names match the glob patterns in `clutter`, which should be a list
+files whose names match the glob patterns in ``clutter``, which should be a list
 of strings. The default list consists of "Thumbs.DB" and ".DS_Store".
 
 The importer only removes recursively searched subdirectories---the top-level
@@ -434,9 +435,9 @@ support ANSI colors.
 
 .. note::
 
-    The `color` option was previously a top-level configuration. This is
+    The ``color`` option was previously a top-level configuration. This is
     still respected, but a deprecation message will be shown until your
-    top-level `color` configuration has been nested under `ui`.
+    top-level ``color`` configuration has been nested under ``ui``.
 
 .. _colors:
 
@@ -728,8 +729,8 @@ languages
 A list of locale names to search for preferred aliases. For example, setting
 this to ``en`` uses the transliterated artist name "Pyotr Ilyich Tchaikovsky"
 instead of the Cyrillic script for the composer's name when tagging from
-MusicBrainz. You can use a space-separated list of language abbreviations, like 
+MusicBrainz. You can use a space-separated list of language abbreviations, like
-``en jp es``, to specify a preference order. Defaults to an empty list, meaning 
+``en jp es``, to specify a preference order. Defaults to an empty list, meaning
 that no language is preferred.
 
 .. _ignored_alias_types:
@@ -739,7 +740,7 @@ ignored_alias_types
 
 A list of alias types to be ignored when importing new items.
 
-See the `MusicBrainz Documentation` for more information on aliases.
+See the ``MusicBrainz Documentation`` for more information on aliases.
 
 .._MusicBrainz Documentation: https://musicbrainz.org/doc/Aliases
 
@@ -801,11 +802,11 @@ Default::
 duplicate_action
 ~~~~~~~~~~~~~~~~
 
-Either ``skip``, ``keep``, ``remove``, ``merge`` or ``ask``. 
+Either ``skip``, ``keep``, ``remove``, ``merge`` or ``ask``.
-Controls how duplicates are treated in import task. 
+Controls how duplicates are treated in import task.
-"skip" means that new item(album or track) will be skipped; 
+"skip" means that new item(album or track) will be skipped;
 "keep" means keep both old and new items; "remove" means remove old
-item; "merge" means merge into one album; "ask" means the user 
+item; "merge" means merge into one album; "ask" means the user
 should be prompted for the action each time. The default is ``ask``.
 
 .. _duplicate_verbose_prompt:
@@ -991,7 +992,11 @@ the penalty name to the ``ignored`` setting::
 
 The available penalties are the same as those for the :ref:`max_rec` setting.
 
-For example, setting ``ignored: missing_tracks`` will skip any album matches where your audio files are missing some of the tracks. The importer will not attempt to display these matches. It does not ignore the fact that the album is missing tracks, which would allow these matches to apply more easily. To do that, you'll want to adjust the penalty for missing tracks.
+For example, setting ``ignored: missing_tracks`` will skip any album matches
+where your audio files are missing some of the tracks. The importer will not
+attempt to display these matches. It does not ignore the fact that the album is
+missing tracks, which would allow these matches to apply more easily. To do
+that, you'll want to adjust the penalty for missing tracks.
 
 .. _required:
 
@@ -1061,8 +1066,8 @@ defaults look like this::
         singleton: Non-Album/$artist/$title
         comp: Compilations/$album%aunique{}/$track $title
 
-Note the use of ``$albumartist`` instead of ``$artist``; this ensures that albums
+Note the use of ``$albumartist`` instead of ``$artist``; this ensures that
-will be well-organized. For more about these format strings, see
+albums will be well-organized. For more about these format strings, see
 :doc:`pathformat`. The ``aunique{}`` function ensures that identically-named
 albums are placed in different directories; see :ref:`aunique` for details.
 

docs/reference/pathformat.rst

@@ -40,7 +40,9 @@ probably don't want that! So use ``$albumartist``.
 .. _Stop Making Sense:
     https://musicbrainz.org/release/798dcaab-0f1a-4f02-a9cb-61d5b0ddfd36.html
 
-As a convenience, however, beets allows ``$albumartist`` to fall back to the value for ``$artist`` and vice-versa if one tag is present but the other is not.
+As a convenience, however, beets allows ``$albumartist`` to fall back to the
+value for ``$artist`` and vice-versa if one tag is present but the other is
+not.
 
 
 .. _template-functions:
@@ -60,13 +62,14 @@ These functions are built in to beets:
 
 * ``%lower{text}``: Convert ``text`` to lowercase.
 * ``%upper{text}``: Convert ``text`` to UPPERCASE.
-* ``%capitalize{text}``: Make the first letter of ``text`` UPPERCASE and the rest lowercase.
+* ``%capitalize{text}``: Make the first letter of ``text`` UPPERCASE and the
+  rest lowercase.
 * ``%title{text}``: Convert ``text`` to Title Case.
 * ``%left{text,n}``: Return the first ``n`` characters of ``text``.
-* ``%right{text,n}``: Return the last ``n`` characters of  ``text``.
+* ``%right{text,n}``: Return the last ``n`` characters of ``text``.
 * ``%if{condition,text}`` or ``%if{condition,truetext,falsetext}``: If
-  ``condition`` is nonempty (or nonzero, if it's a number), then returns
+  ``condition`` is nonempty (or nonzero, if it's a number), then returns the
-  the second argument. Otherwise, returns the third argument if specified (or
+  second argument. Otherwise, returns the third argument if specified (or
   nothing if ``falsetext`` is left off).
 * ``%asciify{text}``: Convert non-ASCII characters to their ASCII equivalents.
   For example, "café" becomes "cafe". Uses the mapping provided by the
@@ -137,8 +140,9 @@ disambiguation if, for example, you include the year by default in
 path formats.
 
 The default characters used as brackets are ``[]``. To change this, provide a
-third argument to the ``%aunique`` function consisting of two characters: the left
+third argument to the ``%aunique`` function consisting of two characters: the
-and right brackets. Or, to turn off bracketing entirely, leave argument blank.
+left and right brackets. Or, to turn off bracketing entirely, leave argument
+blank.
 
 One caveat: When you import an album that is named identically to one already in
 your library, the *first* album—the one already in your library— will not
@@ -157,9 +161,9 @@ It is also possible to have singleton tracks with the same name and the same
 artist. Beets provides the ``%sunique{}`` template to avoid giving these
 tracks the same file path.
 
-It has the same arguments as the :ref:`%aunique <aunique>` template, but the default
+It has the same arguments as the :ref:`%aunique <aunique>` template, but the
-values are different. The default identifiers are ``artist title`` and the
+default values are different. The default identifiers are ``artist title`` and
-default disambiguators are ``year trackdisambig``.
+the default disambiguators are ``year trackdisambig``.
 
 Syntax Details
 --------------

docs/reference/query.rst

@@ -181,8 +181,8 @@ shell).
 Numeric Range Queries
 ---------------------
 
-For numeric fields, such as year, bitrate, and track, you can query using one-
+For numeric fields, such as year, bitrate, and track, you can query using
-or two-sided intervals. That is, you can find music that falls within a
+one-or two-sided intervals. That is, you can find music that falls within a
 *range* of values. To use ranges, write a query that has two dots (``..``) at
 the beginning, middle, or end of a string of numbers. Dots in the beginning
 let you specify a maximum (e.g., ``..7``); dots at the end mean a minimum
@@ -343,7 +343,7 @@ filesystem.
 Sort Order
 ----------
 
-Queries can specify a sort order. Use the name of the `field` you want to sort
+Queries can specify a sort order. Use the name of the ``field`` you want to sort
 on, followed by a ``+`` or ``-`` sign to indicate ascending or descending
 sort. For example, this command::