API - update endpoints documentation

fittrackee/users/auth.py

@@ -954,22 +954,22 @@ def edit_user_preferences(auth_user: User) -> Union[Dict, HttpResponse]:
 
     :<json string date_format: the format used to display dates in the app
     :<json boolean display_ascent: display highest ascent records and total
-    :<json boolean hide_profile_in_users_directory: if true, user does not
+    :<json boolean hide_profile_in_users_directory: if ``true``, user does not
                                                     appear in users directory
     :<json boolean imperial_units: display distance in imperial units
     :<json string language: language preferences
-    :<json string map_visibility: workouts map visibility
-                                  ('public', 'followers_only', 'private')
-    :<json boolean manually_approves_followers: if false, follow requests are
-                        automatically approved
+    :<json string map_visibility: workout map visibility
+                  (``public``, ``followers_only``, ``private``)
+    :<json boolean manually_approves_followers: if ``false``, follow requests
+                  are automatically approved
     :<json boolean start_elevation_at_zero: do elevation plots start at zero?
     :<json string timezone: user time zone
-    :<json boolean use_dark_mode: Display interface with dark mode if true.
-                   If null, it uses browser preferences.
+    :<json boolean use_dark_mode: Display interface with dark mode if ``true``.
+                   If ``null``, it uses browser preferences.
     :<json boolean use_raw_gpx_speed: Use unfiltered gpx to calculate speeds
     :<json boolean weekm: does week start on Monday?
     :<json string workouts_visibility: user workouts visibility
-                                      ('public', 'followers_only', 'private')
+                  (``public``, ``followers_only``, ``private``)
 
     :reqheader Authorization: OAuth 2.0 Bearer Token
 

fittrackee/users/follow_requests.py

@@ -180,7 +180,7 @@ def accept_follow_request(
     auth_user: User, user_name: str
 ) -> Union[Dict, HttpResponse]:
     """
-    Accept a follow request.
+    Accept a follow request from user.
 
     **Scope**: ``follow:write``
 
@@ -229,7 +229,7 @@ def reject_follow_request(
     auth_user: User, user_name: str
 ) -> Union[Dict, HttpResponse]:
     """
-    Reject a follow request.
+    Reject a follow request from user.
 
     **Scope**: ``follow:write``
 

fittrackee/users/users.py

@@ -215,13 +215,13 @@ def get_users(auth_user: User) -> Dict:
                             (default: ``username``)
     :query boolean with_following: returns hidden users followed by user if
            true
-    :query boolean with_hidden_users: returns hidden users if true (only if
+    :query boolean with_hidden_users: returns hidden users if ``true`` (only if
            authenticated user has administration rights - for users
            administration)
-    :query boolean with_inactive: returns inactive users if true (only if
+    :query boolean with_inactive: returns inactive users if ``true`` (only if
            authenticated user has administration rights - for users
            administration)
-    :query boolean with_suspended: returns suspended users if true (only if
+    :query boolean with_suspended: returns suspended users if ``true`` (only if
            authenticated user has administration rights - for users
            administration)
 
@@ -636,7 +636,8 @@ def update_user(auth_user: User, user_name: str) -> Union[Dict, HttpResponse]:
     :param string user_name: user name
 
     :<json boolean activate: (de-)activate user account
-    :<json boolean role: user role ('user', 'admin', 'owner')
+    :<json boolean role: user role (``user``, ``admin``, ``moderator``).
+                   ``owner`` can only be set via **CLI**.
     :<json boolean new_email: new user email
     :<json boolean reset_password: reset user password
 

fittrackee/workouts/sports.py

@@ -176,7 +176,7 @@ def get_sports(auth_user: User) -> Dict:
 
     :query boolean check_workouts: check if sport has workouts
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token if user is authenticated
 
     :statuscode 200: ``success``
     :statuscode 401:

fittrackee/workouts/workouts.py

@@ -234,8 +234,8 @@ def get_workouts(auth_user: User) -> Union[Dict, HttpResponse]:
     :query string order_by: sorting criteria: ``ave_speed``, ``distance``,
                             ``duration``, ``workout_date`` (default:
                             ``workout_date``)
-    :query string equipment_id: equipment id (if 'none', only workouts without
-                            equipments will be returned)
+    :query string equipment_id: equipment id (if ``none``, only workouts
+                            without equipments will be returned)
     :query string notes: any part (or all) of the workout notes,
                          notes matching is case-insensitive
     :query string description: any part of the workout description;
@@ -489,7 +489,8 @@ def get_workout(
 
     :param string workout_short_id: workout short id
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token for workout with
+               ``public`` or ``followers_only`` visibility
 
     :statuscode 200: ``success``
     :statuscode 401:
@@ -605,7 +606,8 @@ def get_workout_gpx(
 
     :param string workout_short_id: workout short id
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token for workout with
+               ``public`` or ``followers_only`` map visibility
 
     :statuscode 200: ``success``
     :statuscode 401:
@@ -674,7 +676,8 @@ def get_workout_chart_data(
 
     :param string workout_short_id: workout short id
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token for workout with
+               ``public`` or ``followers_only`` map visibility
 
     :statuscode 200: ``success``
     :statuscode 401:
@@ -726,7 +729,8 @@ def get_segment_gpx(
     :param string workout_short_id: workout short id
     :param integer segment_id: segment id
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token for workout with
+               ``public`` or ``followers_only`` map visibility
 
     :statuscode 200: ``success``
     :statuscode 400: ``no gpx file for this workout``
@@ -797,7 +801,8 @@ def get_segment_chart_data(
     :param string workout_short_id: workout short id
     :param integer segment_id: segment id
 
-    :reqheader Authorization: OAuth 2.0 Bearer Token
+    :reqheader Authorization: OAuth 2.0 Bearer Token for workout with
+               ``public`` or ``followers_only`` map visibility
 
     :statuscode 200: ``success``
     :statuscode 400: ``no gpx file for this workout``