fix parse sphinx parse error

+ other small imporvements in docs

Author: goggalaxy

src/galaxy/api/plugin.py

@@ -578,10 +578,11 @@ async def authenticate(self, stored_credentials=None):
 
     async def pass_login_credentials(self, step: str, credentials: Dict[str, str], cookies: List[Dict[str, str]]) \
         -> Union[NextStep, Authentication]:
-        """This method is called if we return galaxy.api.types.NextStep from authenticate or from pass_login_credentials.
+        """This method is called if we return :class:`~galaxy.api.types.NextStep` from :meth:`.authenticate`
+        or :meth:`.pass_login_credentials`.
         This method's parameters provide the data extracted from the web page navigation that previous NextStep finished on.
-        This method should either return galaxy.api.types.Authentication if the authentication is finished
-        or galaxy.api.types.NextStep if it requires going to another cef url.
+        This method should either return :class:`~galaxy.api.types.Authentication` if the authentication is finished
+        or :class:`~galaxy.api.types.NextStep` if it requires going to another cef url.
         This method is called by the GOG Galaxy Client.
 
         :param step: deprecated.

src/galaxy/api/types.py

@@ -144,7 +144,8 @@ class LocalGame:
 class FriendInfo:
     """
     .. deprecated:: 0.56
-    Use: :class:`UserInfo`.
+      Use :class:`UserInfo`.
+
     Information about a friend of the currently authenticated user.
 
     :param user_id: id of the user
@@ -189,7 +190,7 @@ class GameLibrarySettings:
 
     :param game_id: id of the related game
     :param tags: collection of tags assigned to the game
-    :param hidden: indicates if the game should be hidden in GOG Galaxy application
+    :param hidden: indicates if the game should be hidden in GOG Galaxy client
     """
     game_id: str
     tags: Optional[List[str]]
@@ -200,12 +201,18 @@ class GameLibrarySettings:
 class UserPresence:
     """Presence information of a user.
 
+    The GOG Galaxy client will prefer to generate user status basing on `game_id` (or `game_title`)
+    and `in_game_status` fields but if plugin is not capable of delivering it then the `full_status` will be used if
+    available
+
     :param presence_state: the state of the user
     :param game_id: id of the game a user is currently in
     :param game_title: name of the game a user is currently in
-    :param presence_status: detailed user's presence description
+    :param in_game_status: status set by the game itself e.x. "In Main Menu"
+    :param full_status: full user status e.x. "Playing <title_name>: <in_game_status>"
     """
     presence_state: PresenceState
     game_id: Optional[str] = None
     game_title: Optional[str] = None
-    presence_status: Optional[str] = None
+    in_game_status: Optional[str] = None
+    full_status: Optional[str] = None

tests/test_user_presence.py

@@ -12,7 +12,7 @@
 @pytest.mark.asyncio
 async def test_get_user_presence_success(plugin, read, write):
     context = "abc"
-    user_ids = ["666", "13", "42", "69"]
+    user_ids = ["666", "13", "42", "69", "22"]
     plugin.prepare_user_presence_context.return_value = async_return_value(context)
     request = {
         "jsonrpc": "2.0",
@@ -26,25 +26,36 @@ async def test_get_user_presence_success(plugin, read, write):
             PresenceState.Unknown,
             "game-id1",
             None,
-            "unknown state"
+            "unknown state",
+            None
         )),
         async_return_value(UserPresence(
             PresenceState.Offline,
             None,
             None,
-            "Going to grandma's house"
+            "Going to grandma's house",
+            None
         )),
         async_return_value(UserPresence(
             PresenceState.Online,
             "game-id3",
             "game-title3",
-            "Pew pew"
+            "Pew pew",
+            None
         )),
         async_return_value(UserPresence(
             PresenceState.Away,
             None,
             "game-title4",
-            "AFKKTHXBY"
+            "AFKKTHXBY",
+            None
+        )),
+        async_return_value(UserPresence(
+            PresenceState.Away,
+            None,
+            "game-title5",
+            None,
+            "Playing game-title5: In Menu"
         )),
     ]
     await plugin.run()
@@ -67,7 +78,7 @@ async def test_get_user_presence_success(plugin, read, write):
                 "presence": {
                     "presence_state": PresenceState.Unknown.value,
                     "game_id": "game-id1",
-                    "presence_status": "unknown state"
+                    "in_game_status": "unknown state"
                 }
             }
         },
@@ -78,7 +89,7 @@ async def test_get_user_presence_success(plugin, read, write):
                 "user_id": "13",
                 "presence": {
                     "presence_state": PresenceState.Offline.value,
-                    "presence_status": "Going to grandma's house"
+                    "in_game_status": "Going to grandma's house"
                 }
             }
         },
@@ -91,7 +102,7 @@ async def test_get_user_presence_success(plugin, read, write):
                     "presence_state": PresenceState.Online.value,
                     "game_id": "game-id3",
                     "game_title": "game-title3",
-                    "presence_status": "Pew pew"
+                    "in_game_status": "Pew pew"
                 }
             }
         },
@@ -103,7 +114,19 @@ async def test_get_user_presence_success(plugin, read, write):
                 "presence": {
                     "presence_state": PresenceState.Away.value,
                     "game_title": "game-title4",
-                    "presence_status": "AFKKTHXBY"
+                    "in_game_status": "AFKKTHXBY"
+                }
+            }
+        },
+        {
+            "jsonrpc": "2.0",
+            "method": "user_presence_import_success",
+            "params": {
+                "user_id": "22",
+                "presence": {
+                    "presence_state": PresenceState.Away.value,
+                    "game_title": "game-title5",
+                    "full_status": "Playing game-title5: In Menu"
                 }
             }
         },
@@ -246,7 +269,7 @@ async def test_update_user_presence(plugin, write):
                     "presence_state": PresenceState.Online.value,
                     "game_id": "game-id",
                     "game_title": "game-title",
-                    "presence_status": "Pew pew"
+                    "in_game_status": "Pew pew"
                 }
             }
         }