clean up naming of translation pickers

docs/advanced/library.md

@@ -15,13 +15,15 @@ Examples of usage are available in the CLI scripts in the `wpextract.cli` module
 
 Use the [`wpextract.WPDownloader`][wpextract.WPDownloader] class.
 
-Possible customisations include:
+Compared to the CLI, you can:
 
-- Implement highly custom request behaviour by subclassing [`RequestSession`][wpextract.dl.RequestSession] and passing to the `session` parameter.
+- implement highly custom request behaviour by subclassing [`RequestSession`][wpextract.dl.RequestSession] and passing to the `session` argument.
 
 
 ## Extractor
 
 Use the [`wpextract.WPExtractor`][wpextract.WPExtractor] class.
 
-When using this approach, it's possible to use [customised translation pickers](../advanced/multilingual.md#adding-support) by passing subclasses of [`LanguagePicker`][wpextract.parse.translations.LangPicker] to the
+Compared to the CLI, you can:
+
+ - set [customised translation pickers](../advanced/multilingual.md#adding-support) by passing subclasses of [`LanguagePicker`][wpextract.parse.translations.LangPicker] to the `translation_pickers` argument.

docs/advanced/multilingual.md

@@ -36,15 +36,15 @@ Currently the following plugins are supported:
 
     ??? example
         ```html
-        --8<-- "tests/parse/translations/test_pickers/polylang.html:struct"
+        --8<-- "tests/parse/translations/test_pickers/polylang_widget.html:struct"
         ```
 
 
 - Adding to the navbar as a custom dropdown[^dropdown]
 
     ??? example
         ```html
-        --8<-- "tests/parse/translations/test_pickers/generic_polylang.html:struct"
+        --8<-- "tests/parse/translations/test_pickers/polylang_custom_dropdown.html:struct"
         ```
 
 **Does not support**:
@@ -56,16 +56,16 @@ Currently the following plugins are supported:
 ## Adding Support
 
 !!! info "See also"
-    [Using WPextract as a library](library.md) for information on how to run wpextract as a library using additional pickers.
+    To use additional pickers, you must [use WPextract as a library](library.md).
 
-Support can be added by creating a new picker definition inheriting from [`LangPicker`][wpextract.parse.translations.LangPicker].
+Support can be added by creating a new picker definition inheriting from [`LangPicker`][wpextract.parse.translations.LangPicker], and passing to the `translation_pickers` argument of [`WPExtractor`][wpextract.WPExtractor]
 
 This parent class defines two abstract methods which must be implemented:
 
 - [`LangPicker.get_root`][wpextract.parse.translations.LangPicker.get_root] - returns the root element of the picker
 - [`LangPicker.extract`][wpextract.parse.translations.LangPicker.extract] - find the languages, call [`LangPicker.set_current_lang`][wpextract.parse.translations.LangPicker.set_current_lang] and call [`LangPicker.add_translation`][wpextract.parse.translations.LangPicker.add_translation] for each
 
-More complicted pickers may need to override additional methods of the class, but should still ultimately populate the [`LangPicker.translations`][wpextract.parse.translations.LangPicker.translations] and [`LangPicker.current_language`][wpextract.parse.translations.LangPicker.current_language] attributes as the parent class does.
+More complicated pickers may need to override additional methods of the class, but should still ultimately populate the [`LangPicker.translations`][wpextract.parse.translations.LangPicker.translations] and [`LangPicker.current_language`][wpextract.parse.translations.LangPicker.current_language] attributes as the parent class does.
 
 This section will show implementing a new picker with the following simplified markup:
 

src/wpextract/parse/translations/_extractor.py

@@ -6,7 +6,7 @@
 
 import wpextract.parse.translations._pickers as pickers
 
-PICKERS = [pickers.Polylang, pickers.GenericLangSwitcher]
+DEFAULT_PICKERS = [pickers.PolylangWidget, pickers.PolylangCustomDropdown]
 PickerListType = list[type[pickers.LangPicker]]
 
 PageTranslationData = pd.Series
@@ -28,7 +28,7 @@ def extract_translations(
         The doc's language and list of translation links
     """
     if translation_pickers is None:
-        translation_pickers = PICKERS
+        translation_pickers = DEFAULT_PICKERS
 
     if page_doc is None:
         return pd.Series([None, []])

src/wpextract/parse/translations/_pickers.py

@@ -89,27 +89,28 @@ def add_translation(self, href: str, lang: str) -> None:
         )
 
 
-class Polylang(LangPicker):
-    """Language picker from the plugin Polylang.
-
-     `WordPress plugin page <https://wordpress.org/plugins/polylang/>`.
-
-    Has the structure::
-
-        <div id="polylang" class="widget widget_polylang">
-            <ul>
-                <li class="lang-item lang-item-en current-lang lang-item-first">
-                    <a lang="en-US" hreflang="en-US" href="URL">\
-                    <img><span>English</span></a>
-                </li>
-                <li class="lang-item lang-item-20 lang-item-fr">
-                    <a lang="fr-FR" hreflang="fr-FR" href="URL">\
-                    <img><span>Français</span></a>
-                </li>
-                ...
-            </ul>
-        </div>
-
+class PolylangWidget(LangPicker):
+    """Language picker from the plugin Polylang used as a widget.
+
+    [WordPress plugin page](https://wordpress.org/plugins/polylang/)
+
+    Has the structure:
+
+    ```html
+    <div id="polylang" class="widget widget_polylang">
+        <ul>
+            <li class="lang-item lang-item-en current-lang lang-item-first">
+                <a lang="en-US" hreflang="en-US" href="URL">\
+                <img><span>English</span></a>
+            </li>
+            <li class="lang-item lang-item-20 lang-item-fr">
+                <a lang="fr-FR" hreflang="fr-FR" href="URL">\
+                <img><span>Français</span></a>
+            </li>
+            ...
+        </ul>
+    </div>
+    ```
     """
 
     def get_root(self) -> PageElement:
@@ -145,21 +146,25 @@ def extract(self) -> None:
             self.add_translation(href, lang)
 
 
-class GenericLangSwitcher(LangPicker):
-    """A language picker in Polylang-style but using some different markup.
+class PolylangCustomDropdown(LangPicker):
+    """Language picker for an in-the-wild version of polylang.
+
+    This was implemented to support a specific site of interest.
 
-    Finds language pickers in the form:::
+    Finds language pickers in the form:
 
-        <div class="header-lang_switcher switcher-ltr">
-            <div class="current-lang-switcher">
-                <img><span>en</span>
-            </div>
-            <ul>
-                <li class="lang-item lang-item-fr lang-item-first">
-                    <a lang="fr-FR" hreflang="fr-FR" href="">Français</a>
-                </li>
-            </ul>
+    ```html
+    <div class="header-lang_switcher switcher-ltr">
+        <div class="current-lang-switcher">
+            <img><span>en</span>
         </div>
+        <ul>
+            <li class="lang-item lang-item-fr lang-item-first">
+                <a lang="fr-FR" hreflang="fr-FR" href="">Français</a>
+            </li>
+        </ul>
+    </div>
+    ```
     """
 
     def get_root(self) -> PageElement:

tests/parse/translations/test_pickers.py

@@ -10,8 +10,8 @@
 @pytest.mark.parametrize(
     ("picker_cls", "picker_file"),
     [
-        (pickers.Polylang, "polylang.html"),
-        (pickers.GenericLangSwitcher, "generic_polylang.html"),
+        (pickers.PolylangWidget, "polylang_widget.html"),
+        (pickers.PolylangCustomDropdown, "polylang_custom_dropdown.html"),
     ],
 )
 def test_picker(datadir: Path, picker_cls: type[pickers.LangPicker], picker_file: str):