Reorganized index.rst for improved logical flow (#1054)

* reorganized sections without changing any header. Made a few small grammar fixes. * cleaning up examples section. * updating changelog for proposed edits
spotipy-dev · May 21, 2024 · 958ff6a · 958ff6a
1 parent 74330da
commit 958ff6a
Show file tree

Hide file tree

Showing 2 changed files with 71 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `python 3.6` from GitHub Actions CI workflow. Ubuntu 20.04 is not available in GitHub Actions for `python 3.6`.
 - Added extra installation step to TUTORIAL.md for required installation packages.
 - Added Troubleshooting Tips section to TUTORIAL.md to address common installation issues.
+- Added link to Spotipy Tutorial for Beginners under Getting Started. 
 
 ### Changed
 - Changes the YouTube video link for authentication tutorial (the old video was in low definition, the new one is in high definition)
@@ -24,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated links to Spotify in documentation 
 - Fixed error obfuscation when Spotify class is being inherited and an error is raised in the Child's `__init__`
 - Replaced `artist_albums(album_type=...)` with `artist_albums(include_groups=...)` due to an API change.
+- Restructured the tutorial in `index.rst` to improve logical flow and made some minor edits.
 
 ### Fixed
 - Fixed unused description parameter in playlist creation example

diff --git a/docs/index.rst b/docs/index.rst
@@ -8,63 +8,6 @@ Welcome to Spotipy!
 <https://developer.spotify.com/documentation/web-api/>`_. With *Spotipy*
 you get full access to all of the music data provided by the Spotify platform.
 
-Assuming you set the ``SPOTIPY_CLIENT_ID`` and ``SPOTIPY_CLIENT_SECRET``
-environment variables (here is a `video <https://youtu.be/kaBVN8uP358>`_ explaining how to do so). For a longer tutorial with examples included, refer to this `video playlist <https://www.youtube.com/watch?v=tmt5SdvTqUI&list=PLqgOPibB_QnzzcaOFYmY2cQjs35y0is9N&index=1>`_. Below is a quick example of using *Spotipy* to list the
-names of all the albums released by the artist 'Birdy'::
-
-    import spotipy
-    from spotipy.oauth2 import SpotifyClientCredentials
-
-    birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
-    spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
-
-    results = spotify.artist_albums(birdy_uri, album_type='album')
-    albums = results['items']
-    while results['next']:
-        results = spotify.next(results)
-        albums.extend(results['items'])
-
-    for album in albums:
-        print(album['name'])
-
-Here's another example showing how to get 30 second samples and cover art
-for the top 10 tracks for Led Zeppelin::
-
-    import spotipy
-    from spotipy.oauth2 import SpotifyClientCredentials
-
-    lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
-
-    spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
-    results = spotify.artist_top_tracks(lz_uri)
-
-    for track in results['tracks'][:10]:
-        print('track    : ' + track['name'])
-        print('audio    : ' + track['preview_url'])
-        print('cover art: ' + track['album']['images'][0]['url'])
-        print()
-
-Finally, here's an example that will get the URL for an artist image given the
-artist's name::
-
-    import spotipy
-    import sys
-    from spotipy.oauth2 import SpotifyClientCredentials
-
-    spotify = spotipy.Spotify(auth_manager=SpotifyClientCredentials())
-
-    if len(sys.argv) > 1:
-        name = ' '.join(sys.argv[1:])
-    else:
-        name = 'Radiohead'
-
-    results = spotify.search(q='artist:' + name, type='artist')
-    items = results['artists']['items']
-    if len(items) > 0:
-        artist = items[0]
-        print(artist['name'], artist['images'][0]['url'])
-
-
 Features
 ========
 
@@ -80,7 +23,8 @@ Install or upgrade *Spotipy* with::
 
     pip install spotipy --upgrade
 
-Or you can get the source from github at https://github.com/plamere/spotipy
+You can also obtain the source code from the `Spotify GitHub repository <https://github.com/plamere/spotipy>`_.
+
 
 Getting Started
 ===============
@@ -90,20 +34,28 @@ All methods require user authorization. You will need to register your app at
 to get the credentials necessary to make authorized calls
 (a *client id* and *client secret*).
 
+
+
 *Spotipy* supports two authorization flows:
 
-  - The **Authorization Code flow** This method is suitable for long-running applications
+  - **Authorization Code flow** This method is suitable for long-running applications
     which the user logs into once. It provides an access token that can be refreshed.
 
     .. note:: Requires you to add a redirect URI to your application at 
               `My Dashboard <https://developer.spotify.com/dashboard/applications>`_.
               See `Redirect URI`_ for more details.
 
-  - The **Client Credentials flow**  The method makes it possible
+  - **Client Credentials flow**  This method makes it possible
     to authenticate your requests to the Spotify Web API and to obtain
     a higher rate limit than you would with the Authorization Code flow.
 
 
+For guidance on setting your app credentials watch this `video tutorial <https://youtu.be/kaBVN8uP358>`_ or follow the
+`Spotipy Tutorial for Beginners <https://github.com/spotipy-dev/spotipy/blob/2.22.1/TUTORIAL.md>`_.
+
+For a longer tutorial with examples included, refer to this `video playlist <https://www.youtube.com/watch?v=tmt5SdvTqUI&list=PLqgOPibB_QnzzcaOFYmY2cQjs35y0is9N&index=1>`_. 
+
+
 Authorization Code Flow
 =======================
 
@@ -139,6 +91,7 @@ on Windows)::
     export SPOTIPY_CLIENT_SECRET='your-spotify-client-secret'
     export SPOTIPY_REDIRECT_URI='your-app-redirect-url'
 
+
 Scopes
 ------
 
@@ -242,9 +195,64 @@ Feel free to contribute new cache handlers to the repo.
 
 Examples
 =======================
+
+Here is an example of using *Spotipy* to list the
+names of all the albums released by the artist 'Birdy'::
+
+    import spotipy
+    from spotipy.oauth2 import SpotifyClientCredentials
+
+    birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
+    spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
+
+    results = spotify.artist_albums(birdy_uri, album_type='album')
+    albums = results['items']
+    while results['next']:
+        results = spotify.next(results)
+        albums.extend(results['items'])
+
+    for album in albums:
+        print(album['name'])
+
+Here's another example showing how to get 30 second samples and cover art
+for the top 10 tracks for Led Zeppelin::
+
+    import spotipy
+    from spotipy.oauth2 import SpotifyClientCredentials
+
+    lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
+
+    spotify = spotipy.Spotify(client_credentials_manager=SpotifyClientCredentials())
+    results = spotify.artist_top_tracks(lz_uri)
+
+    for track in results['tracks'][:10]:
+        print('track    : ' + track['name'])
+        print('audio    : ' + track['preview_url'])
+        print('cover art: ' + track['album']['images'][0]['url'])
+        print()
+
+Finally, here's an example that will get the URL for an artist image given the
+artist's name::
+
+    import spotipy
+    import sys
+    from spotipy.oauth2 import SpotifyClientCredentials
+
+    spotify = spotipy.Spotify(auth_manager=SpotifyClientCredentials())
+
+    if len(sys.argv) > 1:
+        name = ' '.join(sys.argv[1:])
+    else:
+        name = 'Radiohead'
+
+    results = spotify.search(q='artist:' + name, type='artist')
+    items = results['artists']['items']
+    if len(items) > 0:
+        artist = items[0]
+        print(artist['name'], artist['images'][0]['url'])
 
 There are many more examples of how to use *Spotipy* in the `Examples
-Directory <https://github.com/plamere/spotipy/tree/master/examples>`_ on Github
+Directory <https://github.com/plamere/spotipy/tree/master/examples>`_ on GitHub.
 
 API Reference
 ==============