lastgenre: Docs for genre ignorelist feature

Author: JOJ0

docs/plugins/lastgenre.rst

@@ -160,6 +160,58 @@ genres remain, set ``whitelist: no``).
     If ``force`` is disabled the ``keep_existing`` option is simply ignored
     (since ``force: no`` means ``not touching`` existing tags anyway).
 
+Genre Ignorelist
+----------------
+
+Last.fm tags are crowd-sourced, so they can be wrong — especially for artists
+whose names are shared with or confused with others. For example, a "Drum And
+Bass" artist named "Fracture" might incorrectly receive "Metal" tags. The
+ignorelist lets you reject specific genres globally or per-artist.
+
+Another example for the ignorelist is to exclude genres that are technically
+correct but not useful to you. For example, you might want to exclude "Ska" for
+"Bob Marley", even though it is a valid genre for his music.
+
+Filtering is done in two places: when fetching genres from Last.fm and when
+resolving to a final genre list (during canonicalization and whitelisting).
+
+This means that existing genres are also filtered when ``force`` and
+``keep_existing`` options are enabled (or ``cleanup_existing`` is enabled with
+``force`` disabled).
+
+To enable this feature, add an ``ignorelist`` section to your ``lastgenre``
+configuration:
+
+.. code-block:: yaml
+
+    lastgenre:
+        ignorelist:
+            fracture:
+                - ^(heavy|black|power|death)?\s?(metal|rock)$|\w+-metal\d*$
+                - progressive metal
+            bob marley:
+                - ska
+            '*':
+                - electronic
+
+A combination of regex patterns and plain genre names is possible. The ``'*'``
+key applies globally to all artists — use it to block genres you never want,
+regardless of artist. Patterns are matched against the full genre string, so a
+plain ``metal`` will not match ``heavy metal`` unless you write a regex like
+``.*metal``.
+
+.. attention::
+
+    - The global key ``'*'`` **must** be surrounded by single quotes so that
+      YAML does not interpret it as an anchor.
+    - Any regex pattern that starts with a special YAML character (``[``, ``*``,
+      or ``:``) or ends with ``:`` **must** be surrounded by quotes.
+    - Prefer **single quotes** (``'...'``) when quoting is necessary, as they
+      treat backslashes literally (no double-escaping required).
+    - Because the ignorelist uses plain YAML, you do **not** need to
+      double-escape backslashes in unquoted or single-quoted strings (e.g., use
+      ``\w``, not ``\\w``).
+
 Configuration
 -------------
 
@@ -200,6 +252,9 @@ file. The available options are:
   internal whitelist, or ``no`` to consider all genres valid. Default: ``yes``.
 - **title_case**: Convert the new tags to TitleCase before saving. Default:
   ``yes``.
+- **ignorelist**: A mapping of artist names (or the global ``'*'`` key) to lists
+  of genres to exclude. See `Genre Ignorelist`_ for more details. Default:
+  ``no``.
 
 Running Manually
 ----------------