Make lyrics plugin documentation slightly more clear

beetsplug/lyrics.py

@@ -893,8 +893,10 @@ class LyricsPlugin(plugins.BeetsPlugin):
                 "dist_thresh": 0.11,
                 "google_API_key": None,
                 "google_engine_ID": "009217259823014548361:lndtuqkycfu",
-                "genius_api_key": "Ryq93pUGm8bM6eUWwD_M3NOFFDAtp2yEE7W"
+                "genius_api_key": (
-                "76V-uFL5jks5dNvcGCdarqFjDhP9c",
+                    "Ryq93pUGm8bM6eUWwD_M3NOFFDAtp2yEE7W"
+                    "76V-uFL5jks5dNvcGCdarqFjDhP9c"
+                ),
                 "fallback": None,
                 "force": False,
                 "local": False,

docs/plugins/lyrics.rst

@@ -2,25 +2,27 @@ Lyrics Plugin
 =============
 
 The ``lyrics`` plugin fetches and stores song lyrics from databases on the Web.
-Namely, the current version of the plugin uses `Genius.com`_, `Tekstowo.pl`_, `LRCLIB`_
+Namely, the current version of the plugin uses `Genius.com`_, `Tekstowo.pl`_,
-and, optionally, the Google custom search API.
+`LRCLIB`_ and, optionally, the Google Custom Search API.
 
 .. _Genius.com: https://genius.com/
 .. _Tekstowo.pl: https://www.tekstowo.pl/
 .. _LRCLIB: https://lrclib.net/
 
 
-Fetch Lyrics During Import
+Install
---------------------------
+-------
 
-To automatically fetch lyrics for songs you import, first enable it in your
+Firstly, enable ``lyrics`` plugin in your configuration (see
-configuration (see :ref:`using-plugins`). Then, install ``beets`` with
+:ref:`using-plugins`). Then, install ``beets`` with ``lyrics`` extra
-``lyrics`` extra
 
 .. code-block:: bash
 
     pip install "beets[lyrics]"
 
+Fetch Lyrics During Import
+--------------------------
+
 When importing new files, beets will now fetch lyrics for files that don't
 already have them. The lyrics will be stored in the beets database. If the
 ``import.write`` config option is on, then the lyrics will also be written to
@@ -29,52 +31,52 @@ the files' tags.
 Configuration
 -------------
 
-To configure the plugin, make a ``lyrics:`` section in your
+To configure the plugin, make a ``lyrics:`` section in your configuration file.
-configuration file. The available options are:
+Default configuration:
+
+.. code-block:: yaml
+
+    lyrics:
+        auto: yes
+        bing_client_secret: null
+        bing_lang_from: []
+        bing_lang_to: null
+        dist_thresh: 0.11
+        fallback: null
+        force: no
+        google_API_key: null
+        google_engine_ID: 009217259823014548361:lndtuqkycfu
+        sources: [lrclib, google, genius, tekstowo]
+        synced: no
+
+The available options are:
 
 - **auto**: Fetch lyrics automatically during import.
-  Default: ``yes``.
 - **bing_client_secret**: Your Bing Translation application password
-  (to :ref:`lyrics-translation`)
+  (see :ref:`lyrics-translation`)
 - **bing_lang_from**: By default all lyrics with a language other than
   ``bing_lang_to`` are translated. Use a list of lang codes to restrict the set
   of source languages to translate.
-  Default: ``[]``
 - **bing_lang_to**: Language to translate lyrics into.
-  Default: None.
 - **dist_thresh**: The maximum distance between the artist and title
   combination of the music file and lyrics candidate to consider them a match.
   Lower values will make the plugin more strict, higher values will make it
   more lenient. This does not apply to the ``lrclib`` backend as it matches
   durations.
-  Default: ``0.11``.
 - **fallback**: By default, the file will be left unchanged when no lyrics are
   found. Use the empty string ``''`` to reset the lyrics in such a case.
-  Default: None.
 - **force**: By default, beets won't fetch lyrics if the files already have
   ones. To instead always fetch lyrics, set the ``force`` option to ``yes``.
-  Default: ``no``.
 - **google_API_key**: Your Google API key (to enable the Google Custom Search
   backend).
-  Default: None.
 - **google_engine_ID**: The custom search engine to use.
   Default: The `beets custom search engine`_, which gathers an updated list of
   sources known to be scrapeable.
 - **sources**: List of sources to search for lyrics. An asterisk ``*`` expands
-  to all available sources.
+  to all available sources. The ``google`` source will be automatically
-  Default: ``lrclib google genius tekstowo``, i.e., all the available sources. The
+  deactivated if no ``google_API_key`` is setup.
-  ``google`` source will be automatically deactivated if no ``google_API_key``
+- **synced**: Prefer synced lyrics over plain lyrics if a source offers them.
-  is setup.
+  Currently ``lrclib`` is the only source that provides them.
-  The ``google``, ``genius``, and ``tekstowo`` sources will only be enabled if
-  BeautifulSoup is installed.
-- **synced**: Prefer synced lyrics over plain lyrics if a source offers them. Currently `lrclib` is the only source that provides them. Default: `no`.
-
-Here's an example of ``config.yaml``::
-
-    lyrics:
-      fallback: ''
-      google_API_key: AZERTYUIOPQSDFGHJKLMWXCVBN1234567890_ab
-      google_engine_ID: 009217259823014548361:lndtuqkycfu
 
 .. _beets custom search engine: https://www.google.com:443/cse/publicurl?cx=009217259823014548361:lndtuqkycfu
 
@@ -89,74 +91,74 @@ by that band, and ``beet lyrics`` will get lyrics for my entire library. The
 lyrics will be added to the beets database and, if ``import.write`` is on,
 embedded into files' metadata.
 
-The ``-p`` option to the ``lyrics`` command makes it print lyrics out to the
+The ``-p, --print`` option to the ``lyrics`` command makes it print lyrics out
-console so you can view the fetched (or previously-stored) lyrics.
+to the console so you can view the fetched (or previously-stored) lyrics.
 
-The ``-f`` option forces the command to fetch lyrics, even for tracks that
+The ``-f, --force`` option forces the command to fetch lyrics, even for tracks
-already have lyrics. Inversely, the ``-l`` option restricts operations
+that already have lyrics.
-to lyrics that are locally available, which show lyrics faster without using
+
-the network at all.
+Inversely, the ``-l, --local`` option restricts operations to lyrics that are
+locally available, which show lyrics faster without using the network at all.
 
 Rendering Lyrics into Other Formats
 -----------------------------------
 
-The ``-r directory`` option renders all lyrics as `reStructuredText`_ (ReST)
+The ``-r directory, --write-rest directory`` option renders all lyrics as
-documents in ``directory`` (by default, the current directory). That
+`reStructuredText`_ (ReST) documents in ``directory`` (by default, the current
-directory, in turn, can be parsed by tools like `Sphinx`_ to generate HTML,
+directory). That directory, in turn, can be parsed by tools like `Sphinx`_ to
-ePUB, or PDF documents.
+generate HTML, ePUB, or PDF documents.
 
-A minimal ``conf.py`` and ``index.rst`` files are created the first time the
+Minimal ``conf.py`` and ``index.rst`` files are created the first time the
 command is run. They are not overwritten on subsequent runs, so you can safely
 modify these files to customize the output.
 
-.. _Sphinx: https://www.sphinx-doc.org/
+Sphinx supports various `builders`_, see a few suggestions:
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
 
-Sphinx supports various `builders
-<https://www.sphinx-doc.org/en/stable/builders.html>`_, but here are a
-few suggestions.
 
- * Build an HTML version::
+.. admonition:: Build an HTML version
+
+  ::
 
       sphinx-build -b html . _build/html
 
- * Build an ePUB3 formatted file, usable on ebook readers::
+.. admonition:: Build an ePUB3 formatted file, usable on ebook readers
+
+  ::
 
       sphinx-build -b epub3 . _build/epub
 
- * Build a PDF file, which incidentally also builds a LaTeX file::
+.. admonition:: Build a PDF file, which incidentally also builds a LaTeX file
+
+  ::
 
       sphinx-build -b latex %s _build/latex && make -C _build/latex all-pdf
 
-.. _activate-google-custom-search:
+
+.. _Sphinx: https://www.sphinx-doc.org/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _builders: https://www.sphinx-doc.org/en/stable/builders.html
 
 Activate Google Custom Search
 ------------------------------
 
 You need to `register for a Google API key`_. Set the ``google_API_key``
 configuration option to your key.
+
 Then add ``google`` to the list of sources in your configuration (or use
 default list, which includes it as long as you have an API key).
 If you use default ``google_engine_ID``, we recommend limiting the sources to
 ``google`` as the other sources are already included in the Google results.
 
-.. _register for a Google API key: https://console.developers.google.com/
-
 Optionally, you can `define a custom search engine`_. Get your search engine's
 token and use it for your ``google_engine_ID`` configuration option. By
 default, beets use a list of sources known to be scrapeable.
 
-.. _define a custom search engine: https://www.google.com/cse/all
-
 Note that the Google custom search API is limited to 100 queries per day.
 After that, the lyrics plugin will fall back on other declared data sources.
 
-.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/
+.. _register for a Google API key: https://console.developers.google.com/
+.. _define a custom search engine: https://www.google.com/cse/all
 
-Activate Genius and Tekstowo.pl Lyrics
---------------------------------------
-
-These backends are enabled by default.
 
 .. _lyrics-translation:
 
@@ -167,6 +169,6 @@ You need to register for a Microsoft Azure Marketplace free account and
 to the `Microsoft Translator API`_. Follow the four steps process, specifically
 at step 3 enter ``beets`` as *Client ID* and copy/paste the generated
 *Client secret* into your ``bing_client_secret`` configuration, alongside
-``bing_lang_to`` target `language code`.
+``bing_lang_to`` target ``language code``.
 
 .. _Microsoft Translator API: https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-how-to-signup