Documentation updates

docs/index.rst

@@ -1,28 +1,177 @@
-.. spotipy documentation master file, created by
-   sphinx-quickstart on Thu Aug 21 11:04:39 2014.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to spotipy's documentation!
+Spotipy
 ===================================
+Spotipy is a lightweight Python library for the `Spotify Web API
+<https://developer.spotify.com/web-api/>`_. With *spotipy*
+you get full access to all of the music data provided by the Spotify platform. 
 
-Contents:
+Here's a quick example of using *spotipy* to list the names of all the albums
+released by the artist 'Birdy'::
 
-.. toctree::
-   :maxdepth: 2
+    import spotipy
+
+    birdy_uri = 'spotify:artist:2WX2uTcsvV5OnS0inACecP'
+    spotify = spotipy.Spotify()
+
+    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'])
+        print album
+
+Here's another example showing how to get 30 second samples and cover art
+for the top 10 tracks for Led Zeppelin::
+
+    import spotipy
+
+    lz_uri = 'spotify:artist:36QJpDe2go2KgaRleHCDTp'
+
+    spotify = spotipy.Spotify()
+    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
+
+    spotify = spotipy.Spotify()
+
+    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']
 
-$project
-========
 
 Features
 ========
+*Spotipy* supports all of the features of the Spotify Web API including access
+to all end points, and support for user authorization.
 
 Installation
 ============
+Install spotipy with::
+
+    pip install SpotifyWebAPI
+
+Or with::
+
+    easy_install SpotifyWebAPI
+
+Or you can get the source from github at https://github.com/plamere/spotipy
 
 Getting Started
 ===============
 
+To use *spotipy* import the spotipy package, and create a Spotify object.  For
+methods that require authorization, pass the authorization token into the
+Spotify constructor
+
+Non authorized requests::
+
+    import spotipy
+    spotify = spotipy.Spotify()
+    results = spotify.search(q='artist:' + name, type='artist')
+    print results
+
+Authorization
+-------------
+Many methods require user authentication. For these requests you will need to
+generate an authorization token that indicates that the user has granted
+permission for your application to perform the given task. Spotipy provides a
+utility method ``util.prompt_for_user_token`` that will attempt to authorize the
+user.  You can pass your app credentials directly into the method as arguments,
+or if you are reluctant to immortalize your app credentials in your source code, 
+you can set environment variables like so::
+
+    export CLIENT_ID='your-spotify-client-id'
+    export CLIENT_SECRET='your-spotify-client-secret'
+    export REDIRECT_URI='your-app-redirect-url'
+
+Call ``util.prompt_for_user_token`` method with the username and the 
+desired scope (see `Using
+Scopes <https://developer.spotify.com/web-api/using-scopes/>`_ for information
+about scopes) and credentials. This will coordinate the user authorization via
+a the browser.  The credentials are cached locally 
+
+
+Authorized requests::
+
+    import sys
+    import spotipy
+    import spotipy.util as util
+
+    scope = 'user-library-read'
+
+    if len(sys.argv) > 1:
+        username = sys.argv[1]
+    else:
+        print "Usage: %s username" % (sys.argv[0],)
+        sys.exit()
+
+    token = util.prompt_for_user_token(username, scope)
+
+    if token:
+        sp = spotipy.Spotify(auth=token)
+        results = sp.current_user_saved_tracks()
+        for item in results['items']:
+            track = item['track']
+            print track['name'] + ' - ' + track['artists'][0]['name']
+    else:
+        print "Can't get token for", username
+
+
+spotipy Package
+===============
+
+:mod:`spotipy` Package
+----------------------
+
+.. automodule:: spotipy.__init__
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`client` Module
+--------------------
+
+.. automodule:: spotipy.client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`oauth2` Module
+--------------------
+
+.. automodule:: spotipy.oauth2
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+:mod:`util` Module
+------------------
+
+.. automodule:: spotipy.util
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 Support
 =======