[doc] Update documentation about protection

Change-Id: Id92c696f68e83376db7f09b1346046d9596bbfa1
---
M pywikibot/site/_apisite.py
M pywikibot/page/_page.py
2 files changed, 106 insertions(+), 29 deletions(-)

diff --git a/pywikibot/page/_page.py b/pywikibot/page/_page.py
index bd2283a..1b424ed 100644
--- a/pywikibot/page/_page.py
+++ b/pywikibot/page/_page.py
@@ -31,7 +31,15 @@
 
 import pywikibot
 from pywikibot import Timestamp, config, date, i18n, textlib
-from pywikibot.backports import Generator, Iterable, Iterator, List, Set
+from pywikibot.backports import (
+    Dict,
+    Generator,
+    Iterable,
+    Iterator,
+    List,
+    Set,
+    Tuple,
+)
 from pywikibot.cosmetic_changes import CANCEL, CosmeticChangesToolkit
 from pywikibot.exceptions import (
     Error,
@@ -1049,12 +1057,38 @@
             content=content,
         )
 
-    def protection(self) -> dict:
-        """Return a dictionary reflecting page protections."""
+    def protection(self) -> Dict[str, Tuple[str, str]]:
+        """Return a dictionary reflecting page protections.
+
+        **Example:**
+
+        >>> site = pywikibot.Site('wikipedia:test')
+        >>> page = pywikibot.Page(site, 'Main Page')
+        >>> page.protection()
+        {'edit': ('sysop', 'infinity'), 'move': ('sysop', 'infinity')}
+
+        .. seealso::
+           - :meth:`Site.page_restrictions()
+             <pywikibot.site._apisite.APISite.page_restrictions>`
+           - :meth:`applicable_protections`
+           - :meth:`protect`
+        """
         return self.site.page_restrictions(self)
 
     def applicable_protections(self) -> Set[str]:
-        """Return the protection types allowed for that page."""
+        """Return the protection types allowed for that page.
+
+        **Example:**
+
+        >>> site = pywikibot.Site('wikipedia:test')
+        >>> page = pywikibot.Page(site, 'Main Page')
+        >>> sorted(page.applicable_protections())
+        ['edit', 'move']
+
+        .. seealso::
+           - :meth:`protect`
+           - :meth:`protection`
+        """
         self.site.loadpageinfo(self)
         return self._applicable_protections
 
@@ -2008,27 +2042,35 @@
 
     def protect(self,
                 reason: Optional[str] = None,
-                protections: Optional[dict] = None,
+                protections: Optional[Dict[str, Optional[str]]] = None,
                 **kwargs) -> None:
-        """
-        Protect or unprotect a wiki page. Requires administrator status.
+        """Protect or unprotect a wiki page. Requires  *protect* right.
 
-        Valid protection levels are '' (equivalent to 'none'),
-        'autoconfirmed', 'sysop' and 'all'. 'all' means 'everyone is allowed',
-        i.e. that protection type will be unprotected.
+        Valid protection levels are ``''`` (equivalent to ``None``),
+        ``'autoconfirmed'``, ``'sysop'`` and ``'all'``. ``'all'`` means
+        everyone is allowed, i.e. that protection type will be
+        unprotected.
 
-        In order to unprotect a type of permission, the protection level shall
-        be either set to 'all' or '' or skipped in the protections dictionary.
+        In order to unprotect a type of permission, the protection level
+        shall be either set to ``'all'`` or ``''`` or skipped in the
+        protections dictionary.
 
-        Expiry of protections can be set via kwargs, see Site.protect() for
+        Expiry of protections can be set via *kwargs*, see
+        :meth:`Site.protect()<pywikibot.site._apisite.APISite.protect>` for
         details. By default there is no expiry for the protection types.
 
-        :param protections: A dict mapping type of protection to protection
-            level of that type. Allowed protection types for a page can be
-            retrieved by Page.self.applicable_protections()
+        .. seealso::
+           - :meth:`Site.protect()
+             <pywikibot.site._apisite.APISite.protect>`
+           - :meth:`applicable_protections`
+
+        :param protections: A dict mapping type of protection to
+            protection level of that type. Allowed protection types for
+            a page can be retrieved by :meth:`applicable_protections`.
             Defaults to protections is None, which means unprotect all
             protection types.
-            Example: {'move': 'sysop', 'edit': 'autoconfirmed'}
+
+            Example: ``{'move': 'sysop', 'edit': 'autoconfirmed'}``
 
         :param reason: Reason for the action, default is None and will set an
             empty string.
diff --git a/pywikibot/site/_apisite.py b/pywikibot/site/_apisite.py
index c892912..da2b051 100644
--- a/pywikibot/site/_apisite.py
+++ b/pywikibot/site/_apisite.py
@@ -55,7 +55,7 @@
 )
 from pywikibot.login import LoginStatus as _LoginStatus
 from pywikibot.site._basesite import BaseSite
-from pywikibot.site._decorators import need_right
+from pywikibot.site._decorators import need_right, need_version
 from pywikibot.site._extensions import (
     EchoMixin,
     FlowMixin,
@@ -1393,7 +1393,17 @@
         self,
         page: 'pywikibot.page.BasePage'
     ) -> Dict[str, Tuple[str, str]]:
-        """Return a dictionary reflecting page protections."""
+        """Return a dictionary reflecting page protections.
+
+        **Example:**
+
+        >>> site = pywikibot.Site('wikipedia:test')
+        >>> page = pywikibot.Page(site, 'Main Page')
+        >>> site.page_restrictions(page)
+        {'edit': ('sysop', 'infinity'), 'move': ('sysop', 'infinity')}
+
+        .. seealso:: :meth:`page.BasePage.protection` (should be preferred)
+        """
         if not hasattr(page, '_protection'):
             self.loadpageinfo(page)
         return page._protection
@@ -2523,21 +2533,33 @@
         """
         Return the protection types available on this site.
 
+        **Example:**
+
+        >>> site = pywikibot.Site('wikipedia:test')
+        >>> sorted(site.protection_types())
+        ['create', 'edit', 'move', 'upload']
+
         .. seealso:: :py:obj:`Siteinfo._get_default()`
 
         :return: protection types available
         """
         return set(self.siteinfo.get('restrictions')['types'])
 
+    @need_version('1.27.3')
     def protection_levels(self) -> Set[str]:
         """
         Return the protection levels available on this site.
 
+        **Example:**
+
+        >>> site = pywikibot.Site('wikipedia:test')
+        >>> sorted(site.protection_levels())
+        ['', 'autoconfirmed', ... 'sysop', 'templateeditor']
+
         .. seealso:: :py:obj:`Siteinfo._get_default()`
 
         :return: protection types available
         """
-        # implemented in b73b5883d486db0e9278ef16733551f28d9e096d
         return set(self.siteinfo.get('restrictions')['levels'])
 
     @need_right('protect')
@@ -2549,19 +2571,23 @@
         expiry: Union[datetime.datetime, str, None] = None,
         **kwargs: Any
     ) -> None:
-        """(Un)protect a wiki page. Requires administrator status.
+        """(Un)protect a wiki page. Requires *protect* right.
 
-        .. seealso:: :api:`Protect`
+        .. seealso::
+           - :api:`Protect`
+           - :meth:`protection_types`
+           - :meth:`protection_levels`
 
-        :param protections: A dict mapping type of protection to protection
-            level of that type. Valid restriction types are 'edit', 'create',
-            'move' and 'upload'. Valid restriction levels are '' (equivalent
-            to 'none' or 'all'), 'autoconfirmed', and 'sysop'.
-            If None is given, however, that protection will be skipped.
+        :param protections: A dict mapping type of protection to
+            protection level of that type. Refer :meth:`protection_types`
+            for valid restriction types and :meth:`protection_levels`
+            for valid restriction levels. If None is given, however,
+            that protection will be skipped.
         :param reason: Reason for the action
         :param expiry: When the block should expire. This expiry will be
-            applied to all protections. If None, 'infinite', 'indefinite',
-            'never', or '' is given, there is no expiry.
+            applied to all protections. If ``None``, ``'infinite'``,
+            ``'indefinite'``, ``'never'``, or ``''`` is given, there is
+            no expiry.
         """
         token = self.tokens['csrf']
         self.lock_page(page)

