[fix] Use an asterisk as sort key in ar-wiki

- add a new dict main_sortkey to cosmetic_changes to determine the sort
  key for main articles
- don't the sort key from main_sortkey if the main article already has one
- raise a ValueError if main_sortkey is missconfigured
- update documentation

Bug: T370536
Change-Id: I2852baba6c9cebbcd209258388da85abc540d814

pywikibot/cosmetic_changes.py

@@ -64,7 +64,7 @@
 from urllib.parse import urlparse, urlunparse
 
 import pywikibot
-from pywikibot import exceptions, textlib
+from pywikibot import exceptions, i18n, textlib
 from pywikibot.backports import Callable, Match, Pattern
 from pywikibot.site import Namespace
 from pywikibot.textlib import (
@@ -173,6 +173,20 @@
     }
 }
 
+main_sortkey = {
+    '_default': ' ',
+    'ar': '*',
+}
+"""Sort key to specify the main article within a category.
+
+The sort key must be one of ``' '``, ``'!'``, ``'*'``, ``'#'`` and is
+used like a pipe link but sorts the page in front of the alphabetical
+order. This dict is used in
+:meth:`CosmeticChangesToolkit.standardizePageFooter`.
+
+.. versionadded:: 9.3
+"""
+
 
 class CANCEL(IntEnum):
 
@@ -327,22 +341,27 @@ def fixSelfInterwiki(self, text: str) -> str:
         return text
 
     def standardizePageFooter(self, text: str) -> str:
-        """
-        Standardize page footer.
+        """Standardize page footer.
 
-        Makes sure that interwiki links and categories are put
-        into the correct position and into the right order. This
-        combines the old instances of standardizeInterwiki
-        and standardizeCategories.
+        Makes sure that interwiki links and categories are put into the
+        correct position and into the right order.
+
+        The page footer consists of the following parts in that sequence:
 
-        The page footer consists of the following parts
-        in that sequence:
         1. categories
         2. additional information depending on the local site policy
         3. interwiki
-        """
-        assert self.title is not None
 
+        .. versionchanged:: 9.3
+           uses :attr:`main_sortkey` to determine the sort key for the
+           main article within a category. If the main article has a
+           sort key already, it will not be changed any longer.
+
+        :param text: text to be modified
+        :return: the modified *text*
+        :raises ValueError: wrong value of sortkey in
+            :attr:`main_sortkey` for the given site
+        """
         categories = []
         interwiki_links = {}
 
@@ -373,11 +392,21 @@ def standardizePageFooter(self, text: str) -> str:
             # TODO: Sort categories in alphabetic order, e.g. using
             # categories.sort()? (T100265)
             # TODO: Get main categories from Wikidata?
-            main = pywikibot.Category(self.site, 'Category:' + self.title,
-                                      sort_key=' ')
+            main = pywikibot.Category(self.site, 'Category:' + self.title)
             if main in categories:
-                categories.pop(categories.index(main))
+                main = categories.pop(categories.index(main))
+                if main.sortKey:
+                    sortkey = main.sortKey
+                else:
+                    sortkey = i18n.translate(self.site, main_sortkey,
+                                             fallback=['_default'])
+                    if sortkey not in [' ', '*', '!', '#']:
+                        raise ValueError(
+                            f'sort key for {self.site} is {sortkey} but must'
+                            "be one of ' ', '*', '!', '#'")
+                main = pywikibot.Category(main, sort_key=sortkey)
                 categories.insert(0, main)
+
             text = textlib.replaceCategoryLinks(text, categories,
                                                 site=self.site)