From ac96b9b64e97cdca0be6305e939e902e8742f147 Mon Sep 17 00:00:00 2001 From: Noor Date: Wed, 2 Jul 2025 20:40:37 +0200 Subject: [PATCH] Preserve line breaks for example cases in substitution plugin docs (#5846) ## Description Adds line block markup to example substitutions in the plugin documentation, so that each case is shown on a separate line: > 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 group in the output, discarding the rest of the string. > > ```yaml > substitute: > ^(.*?)(,| &| and).*: \1 > ``` > > This would handle all the below cases in a single rule: > >> Bob Dylan and The Band -> Bob Dylan >> Neil Young & Crazy Horse -> Neil Young >> James Yorkston, Nina Persson & The Second Hand Orchestra -> James Yorkston --- docs/changelog.rst | 2 ++ docs/plugins/substitute.rst | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index 1baa54011..0e5799846 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -61,6 +61,8 @@ Other changes: * Documentation structure for auto generated API references changed slightly. Autogenerated API references are now located in the `docs/api` subdirectory. +* :doc:`/plugins/substitute`: Fix rST formatting for example cases so that each + case is shown on separate lines. 2.3.1 (May 14, 2025) -------------------- diff --git a/docs/plugins/substitute.rst b/docs/plugins/substitute.rst index 87ee2ad45..c6fec8054 100644 --- a/docs/plugins/substitute.rst +++ b/docs/plugins/substitute.rst @@ -31,9 +31,9 @@ group in the output, discarding the rest of the string. This would handle all the below cases in a single rule: - Bob Dylan and The Band -> Bob Dylan - Neil Young & Crazy Horse -> Neil Young - James Yorkston, Nina Persson & The Second Hand Orchestra -> James Yorkston + | Bob Dylan and The Band -> Bob Dylan + | 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 the paths section. For example: