metabrainz · alastair · Apr 21, 2021 · Mar 18, 2021 · Mar 18, 2021 · Mar 18, 2021
diff --git a/docs/dev/api.rst b/docs/dev/api.rst
@@ -28,12 +28,13 @@ Core API Endpoints
   Get the timestamp of the newest listen submitted by a user in previous imports to ListenBrainz.
 
   In order to get the timestamp for a user, make a GET request to this endpoint. The data returned will
-  be JSON of the following format::
+  be JSON of the following format:
+
+  .. code-block:: json
 
       {
-          'musicbrainz_id': the MusicBrainz ID of the user,
-          'latest_import': the timestamp of the newest listen submitted in previous imports.
-                           Defaults to 0
+          "musicbrainz_id": "the MusicBrainz ID of the user",
+          "latest_import": "the timestamp of the newest listen submitted in previous imports. Defaults to 0"
       }
 
   :param user_name: the MusicBrainz ID of the user whose data is needed
@@ -46,11 +47,13 @@ Core API Endpoints
 
   In order to update the timestamp of a user, you'll have to provide a user token in the Authorization Header. User tokens can be found on https://listenbrainz.org/profile/.
 
-  The JSON that needs to be posted must contain a field named `ts` in the root with a valid unix timestamp. Example::
+  The JSON that needs to be posted must contain a field named `ts` in the root with a valid unix timestamp. Example:
+
+  .. code-block:: json
 
-    {
-      'ts': 0
-    }
+     {
+        "ts": 0
+     }
 
   :reqheader Authorization: Token <user token>
   :statuscode 200: latest import timestamp updated
@@ -66,6 +69,36 @@ The playlists API allows for the creation and editing of lists of recordings
    :include-empty-docstring:
    :undoc-static:
 
+Feedback API Endpoints
+^^^^^^^^^^^^^^^^^^^^^^
+These API endpoints allow to submit and retrieve feedback for a user's recordings
-These API endpoints allow to submit and retrieve feedback for a user's recordings
+These API endpoints allow to submit and retrieve feedback recordings that a user has listened to
-These API endpoints allow to submit and retrieve feedback for a user's recordings
+These API endpoints allow to submit and retrieve feedback recordings that a user has listened to
+
+.. autoflask:: listenbrainz.webserver:create_app_rtfd()
+   :blueprints: feedback_api_v1
+   :include-empty-docstring:
+   :undoc-static:
+
+Recording Recommendation API Endpoints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ListenBrainz uses collaborative filtering to generate recording recommendations,
+which may be further processed to generate playlists for users. These api endpoints
+allow to fetch the raw collaborative filtered recording IDs.
+
+.. autoflask:: listenbrainz.webserver:create_app_rtfd()
+   :blueprints: recommendations_cf_recording_v1
+   :include-empty-docstring:
+   :undoc-static:
+
+Recording Recommendation Feedback API Endpoints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ListenBrainz uses collaborative filtering to generate recording recommendations,
+which may be further processed to generate playlists for users. These api endpoints
+allow to submit and retrieve feedback for raw collaborative filtered recordings.
+
+.. autoflask:: listenbrainz.webserver:create_app_rtfd()
+   :blueprints: recommendation_feedback_api_v1
+   :include-empty-docstring:
+   :undoc-static:
 
 Statistics API Endpoints
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -86,6 +119,13 @@ Status API Endpoints
    :include-empty-docstring:
    :undoc-static:
 
+User Timeline API Endpoints
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+These api endpoints allow to create and fetch timeline events for a user.
+
+.. autoflask:: listenbrainz.webserver:create_app_rtfd()
+   :blueprints: user_timeline_event_api_bp
+
 Social API Endpoints
 ^^^^^^^^^^^^^^^^^^^^
 These apis allow to interact with social features of ListenBrainz.

diff --git a/docs/dev/feedback-json.rst b/docs/dev/feedback-json.rst
@@ -11,7 +11,9 @@ Submission JSON
 To submit recording feedback via our API (see: :doc:`api`), ``POST`` a JSON document to
 the ``recording-feedback`` endpoint.
 
-A sample feedback may look like::
+A sample feedback may look like:
+
+.. code-block:: json
 
     {
         "recording_msid": "d23f4719-9212-49f0-ad08-ddbfbfc50d6f",
@@ -36,20 +38,22 @@ Score can have one of these three values:
 Fetching feedback JSON
 ----------------------
 
-The JSON documents returned from our API for recording feedback look like the following::
+The JSON documents returned from our API for recording feedback look like the following:
+
+.. code-block:: json
 
     {
-      count: 1,
-      feedback: [
-        {
-            "user_id": "-- the MusicBrainz ID of the user --",
-            "recording_msid": "d23f4719-9212-49f0-ad08-ddbfbfc50d6f",
-            "score": 1
-        },
-        "-- more feedback data here ---"
-      ],
-      offset: 0,
-      total_count: 1
+        "count": 1,
+        "feedback": [
+            {
+                "user_id": "-- the MusicBrainz ID of the user --",
+                "recording_msid": "d23f4719-9212-49f0-ad08-ddbfbfc50d6f",
+                "score": 1
+            },
+            "-- more feedback data here ---"
+        ],
+        "offset": 0,
+        "total_count": 1
     }
 
 The number of feedback items in the document are returned by the top-level ``count`` element. The total number of

diff --git a/docs/dev/json.rst b/docs/dev/json.rst
@@ -38,16 +38,20 @@ the ``submit-listens`` endpoint. Submit one of three types JSON documents:
 The ``listen_type`` element defines different types of submissions. The element
 is placed at the top-most level of the JSON document. The only other required
 element is the ``payload`` element. This provides an array of listens – the
-payload may be one or more listens (as designated by ``listen_type``)::
+payload may be one or more listens (as designated by ``listen_type``):
+
+.. code-block:: json
 
     {
       "listen_type": "single",
       "payload": [
-          --- listen data here ---
+          "--- listen data here ---"
       ]
     }
 
-A sample listen payload may look like::
+A sample listen payload may look like:
+
+.. code-block:: json
 
     {
       "listened_at": 1443521965,
@@ -66,7 +70,9 @@ A sample listen payload may look like::
       }
     }
 
-A complete submit listen JSON document may look like::
+A complete submit listen JSON document may look like:
+
+.. code-block:: json
 
     {
       "listen_type": "single",
@@ -95,7 +101,9 @@ A complete submit listen JSON document may look like::
 Fetching listen JSON
 --------------------
 
-The JSON documents returned from our API look like the following::
+The JSON documents returned from our API look like the following:
+
+.. code-block:: json
 
     {
       "payload": {
@@ -121,7 +129,9 @@ Payload JSON details
 --------------------
 
 A minimal payload must include
-``track_metadata/artist_name`` and ``track_metadata/track_name`` elements::
+``track_metadata/artist_name`` and ``track_metadata/track_name`` elements:
+
+.. code-block:: json
 
     {
       "track_metadata": {

diff --git a/listenbrainz/webserver/views/api.py b/listenbrainz/webserver/views/api.py
@@ -324,10 +324,12 @@ def latest_import():
     In order to get the timestamp for a user, make a GET request to this endpoint. The data returned will
     be JSON of the following format:
 
-    {
-        'musicbrainz_id': the MusicBrainz ID of the user,
-        'latest_import': the timestamp of the newest listen submitted in previous imports. Defaults to 0
-    }
+    .. code-block:: json
+
+        {
+            "musicbrainz_id": "the MusicBrainz ID of the user",
+            "latest_import": "the timestamp of the newest listen submitted in previous imports. Defaults to 0"
+        }
 
     :param user_name: the MusicBrainz ID of the user whose data is needed
     :statuscode 200: Yay, you have data!
@@ -390,21 +392,25 @@ def validate_token():
 
     A JSON response, with the following format, will be returned.
 
-    - If the given token is valid::
+    - If the given token is valid:
+
+    .. code-block:: json
 
         {
             "code": 200,
             "message": "Token valid.",
-            "valid": True,
+            "valid": true,
             "user": "MusicBrainz ID of the user with the passed token"
         }
 
-    - If the given token is invalid::
+    - If the given token is invalid:
+
+    .. code-block:: json
 
         {
             "code": 200,
             "message": "Token invalid.",
-            "valid": False,
+            "valid": false,
         }
 
     :statuscode 200: The user token is valid/invalid.

diff --git a/listenbrainz/webserver/views/missing_musicbrainz_data_api.py b/listenbrainz/webserver/views/missing_musicbrainz_data_api.py
@@ -39,37 +39,40 @@ def get_missing_musicbrainz_data(user_name):
     """ Get musicbrainz data sorted on "listened_at" that the user has submitted to ListenBrainz but has not
         submitted to MusicBrainz.
 
-        A sample response from the endpoint may look like::
-
-        {
-            "payload": {
-
-                "last_updated": 1588494361,
-                "data": [
-                    {
-                        "artist_msid": "fd32e967-b874-44b2-809c-3862f714813c",
-                        "artist_name": "Red City Radio",
-                        "listened_at": "2020-04-29 23:40:47",
-                        "recording_msid": "78f63ece-86e1-48bf-a7ff-29793d4a84e6",
-                        "release_msid": "47818692-f669-4846-acbc-cb0a69987aee",
-                        "release_name": "The Dangers Of Standing Still",
-                        "track_name": "Never Bring A Cup Of Water To A Gunfight"
-                    },
-                    {
-                        "artist_msid": "fd32e967-b874-44b2-809c-3862f714813c",
-                        "artist_name": "Red City Radio",
-                        "listened_at": "2020-04-29 23:37:57",
-                        "recording_msid": "d226200a-a9be-4e9e-9f7c-d74a71647893",
-                        "release_msid": "47818692-f669-4846-acbc-cb0a69987aee",
-                        "release_name": "The Dangers Of Standing Still",
-                        "track_name": "Nathaniel Martinez"
-                    }
-                "count": 2,
-                "offset": 4,
-                "total_data_count": 25,
-                "user_name": "Vansika"
+        A sample response from the endpoint may look like:
+
+        .. code-block:: json
+
+            {
+                "payload":
+                {
+                    "last_updated": 1588494361,
+                    "data": [
+                        {
+                            "artist_msid": "fd32e967-b874-44b2-809c-3862f714813c",
+                            "artist_name": "Red City Radio",
+                            "listened_at": "2020-04-29 23:40:47",
+                            "recording_msid": "78f63ece-86e1-48bf-a7ff-29793d4a84e6",
+                            "release_msid": "47818692-f669-4846-acbc-cb0a69987aee",
+                            "release_name": "The Dangers Of Standing Still",
+                            "track_name": "Never Bring A Cup Of Water To A Gunfight"
+                        },
+                        {
+                            "artist_msid": "fd32e967-b874-44b2-809c-3862f714813c",
+                            "artist_name": "Red City Radio",
+                            "listened_at": "2020-04-29 23:37:57",
+                            "recording_msid": "d226200a-a9be-4e9e-9f7c-d74a71647893",
+                            "release_msid": "47818692-f669-4846-acbc-cb0a69987aee",
+                            "release_name": "The Dangers Of Standing Still",
+                            "track_name": "Nathaniel Martinez"
+                        }
+                    ],
+                    "count": 2,
+                    "offset": 4,
+                    "total_data_count": 25,
+                    "user_name": "Vansika"
+                }
             }
-        }
 
         :param count: Optional, number of records to return, Default: :data:`~webserver.views.api.DEFAULT_ITEMS_PER_GET`
             Max: :data:`~webserver.views.api.MAX_ITEMS_PER_GET`

diff --git a/listenbrainz/webserver/views/recommendations_cf_recording_api.py b/listenbrainz/webserver/views/recommendations_cf_recording_api.py
@@ -26,43 +26,42 @@ class RecommendationArtistType(Enum):
 def get_recommendations(user_name):
     """ Get recommendations sorted on rating and ratings for user ``user_name``.
 
-        A sample response from the endpoint may look like::
-
-        {
-          "payload": {
-
-            "last_updated": 1588494361,
-            "type": <artist_type>,
-            "entity": "recording",
-
-            "mbids": [
-                {
-                    'recording_mbid': "526bd613-fddd-4bd6-9137-ab709ac74cab",
-                    'score': 9.345
-                }
-                {
-                    'recording_mbid': "a6081bc1-2a76-4984-b21f-38bc3dcca3a5",
-                    'score': 6.998
+        A sample response from the endpoint may look like:
+
+        .. code-block:: json
+
+            {
+                "payload": {
+                    "last_updated": 1588494361,
+                    "type": "<artist_type>",
+                    "entity": "recording",
+                    "mbids": [
+                        {
+                            "recording_mbid": "526bd613-fddd-4bd6-9137-ab709ac74cab",
+                            "score": 9.345
+                        },
+                        {
+                            "recording_mbid": "a6081bc1-2a76-4984-b21f-38bc3dcca3a5",
+                            "score": 6.998
+                        }
+                    ],
+                    "user_name": "unclejohn69",
+                    "count": 10,
+                    "total_mbid_count": 30,
+                    "offset": 10
                 }
-            ],
+            }
 
-            "user_name": "unclejohn69"
-            'count': 10,
-            'total_mbid_count': 30
-            'offset': 10
-          }
-        }
-
-        <artist_type>: 'top' or 'similar'
 
         .. note::
             - This endpoint is experimental and probably will change in the future.
+            - <artist_type>: 'top' or 'similar'
 
         :param artist_type: Mandatory, artist type in ['top', 'similar']
-            Ex. artist_type = top will fetch recommended recording mbids that belong to top artists
-                       listened to by the user.
-                artist_type = similar will fetch recommended recording mbids that belong to artists
-                       similar to top artists listened to by the user.
+
+            Ex. artist_type = top will fetch recommended recording mbids that belong to top artists listened to by the user.
+
+            artist_type = similar will fetch recommended recording mbids that belong to artists similar to top artists listened to by the user.
         :type artist_type: ``str``
 
         :param count: Optional, number of recording mbids to return, Default: :data:`~webserver.views.api.DEFAULT_ITEMS_PER_GET`