Merge pull request #135 from praw-dev/auth_docs

Doco - describe refresh_token process

AUTHORS.rst

@@ -26,6 +26,7 @@ Documentation Contributors
 - Tom Eagles `@deplorableword <https://github.com/deplorableword>`_
 - Rémy Pecqueur `@Lordshinjo <https://github.com/Lordshinjo>`_
 - Mohammad Ghalayini `@mghalayini <https://github.com/mghalayini>`_
+- Jason Haines `@jghaines <https://github.com/jghaines>`_
 - Add "Name <email (optional)> and github profile link" above this line.
 
 PRAW Author

docs/getting_started/authentication.rst

@@ -24,6 +24,14 @@ table defines which application types can use which flows:
 
 .. include:: authentication_flow_table.txt
 
+.. warning::
+
+    For the sake of brevity, the following examples pass authentication information via
+    arguments to :class:`.Reddit`. If you do this, you need to be careful not to reveal
+    this information to the outside world if you share your code. It is recommended to
+    use a :ref:`praw.ini file <praw.ini>` in order to keep your authentication
+    information separate from your code.
+
 .. _password_flow:
 
 Password Flow

docs/tutorials/refresh_token.rst

@@ -74,3 +74,19 @@ The following program can be used to obtain a refresh token with the desired sco
 
 .. literalinclude:: ../examples/obtain_refresh_token.py
     :language: python
+
+This script assumes you have configured your application's ``redirect uri`` to
+``localhost:8080``
+
+When you execute this script interactively:
+
+- You will be prompted for a comma-separated list of scopes
+- You will be given a URL that will take you through the auth follow
+- Reddit will ask you for user authentication and ask you to grant the application
+  permissions
+- On completion, the user will have a new authorized application configured
+- A refresh token is displayed in the browser and on the command line
+
+You only have to run this script once for each refresh token. The refresh token (along
+with the application's client_id, client_secret) are valid credentials until manually
+revoked by the user.