Add configuration option page

Also add:

* refresh_token example
* explain how to use proxies

docs/Makefile

@@ -16,6 +16,8 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
+default: html
+
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"

docs/getting_started/authentication.rst

@@ -1,2 +1,4 @@
+.. _oauth:
+
 Authenticating via OAuth
 ========================

docs/getting_started/configuration.rst

@@ -2,3 +2,58 @@
 
 Configuring PRAW
 ================
+
+.. toctree::
+   :maxdepth: 2
+
+   configuration_options
+
+
+Configuration options can be provided to PRAW in one of three ways:
+
+* :ref:`praw.ini`
+* :ref:`reddit_initialization`
+* :ref:`environment_variables`
+
+Environment variables have the highest priority, followed by keyword arguments
+when initializing instances of :class:`.Reddit`, and finally settings in
+``praw.ini`` files.
+
+.. _praw.ini:
+
+praw.ini Files
+--------------
+
+Blah
+
+.. _reddit_initialization:
+
+Keyword Arguments to :class:`.Reddit`
+-------------------------------------
+
+.. _environment_variables:
+
+PRAW Environment Variables
+--------------------------
+
+Blah
+
+
+Using an HTTP or HTTPS proxy with PRAW
+--------------------------------------
+
+PRAW internally relies upon the `requests <http://docs.python-requests.org/>`_
+package to handle HTTP requests. Requests supports use of ``HTTP_PROXY`` and
+``HTTPS_PROXY`` environment variables in order to proxy HTTP and HTTPS requests
+respectively [`ref
+<http://docs.python-requests.org/en/master/user/advanced/#proxies>`_].
+
+Given that PRAW exclusively communicates with Reddit via HTTPS, only the
+`HTTPS_PROXY` option should be required.
+
+If you have a script named ``prawbot.py``, the ``HTTPS_PROXY`` environment
+variable can be provided on the command line like so:
+
+.. code-block:: bash
+
+   HTTPS_PROXY=https://localhost:3128 ./prawbot.py

docs/getting_started/configuration_options.rst

@@ -0,0 +1,114 @@
+Configuration Options
+=====================
+
+PRAW's configuration options are broken down into the following categories:
+
+* :ref:`basic_options`
+* :ref:`oauth_options`
+* :ref:`site_options`
+* :ref:`custom_options`
+
+All of these options can be provided in any of the ways mentioned in
+:ref:`configuration`.
+
+.. _basic_options:
+
+Basic Configuration Options
+---------------------------
+
+:check_for_updates: When ``true``, check for new versions of PRAW. When a
+                    newever version of PRAW is available a message is reported
+                    via standard out (default: ``true``).
+
+:user_agent: (Required) A unique description of your application. The following
+             format is recommended according to `Reddit's API Rules
+             <https://github.com/reddit/reddit/wiki/API#rules>`_:
+             ``<platform>:<app ID>:<version string> (by /u/<reddit
+             username>)``.
+
+.. _oauth_options:
+
+OAuth Configuration Options
+---------------------------
+
+:client_id: (Required) The OAuth client id associated with your registered
+            Reddit application. See :ref:`oauth` for instructions on
+            registering a Reddit application.
+
+:client_secret: The OAuth client secret associated with your registered Reddit
+                application. For web applications, and script applications this
+                field is required. This option cannot be provided for installed
+                applications.
+
+:refresh_token: For web applications, or installed applications using the code
+                flow, you can directly provide a previously obtained refresh
+                token. This option is useful, for example, if you prefer to not
+                have your username and password available to your program, as
+                required for a script application. See: :ref:`refresh_token`
+
+:redirect_uri: The redirect URI associated with your registered Reddit
+               application. For web applications, and installed applications,
+               this field is required. This field is unused for script
+               applications.
+
+:password: The password of the Reddit account associated with your registered
+           Reddit script application. PRAW assumes it is working with a script
+           application when this option is provided.
+
+:username: The username of the Reddit account associated with your registered
+           Reddit script application. PRAW assumes it is working with a script
+           application when this option is provided.
+
+.. _site_options:
+
+Reddit Site Configuration Options
+---------------------------------
+
+PRAW can be configured to work with instances of Reddit which are not hosted at
+reddit.com. The following options may need to be updated in order to
+successfully access a third-party Reddit site:
+
+:comment_kind: The type prefix for comments on the Reddit instance (default:
+               ``t1_``).
+
+:message_kind: The type prefix for messages on the Reddit instance (default:
+               ``t4_``).
+
+:oauth_url: The URL used to access the Reddit instance's API (default:
+            https://oauth.reddit.com).
+
+:reddit_url: The URL used to access the Reddit instance. PRAW assumes the
+             endpoints for establishing OAuth authorization are accessible
+             under this URL (default: https://www.reddit.com).
+
+:redditor_kind: The type prefix for redditors on the Reddit instance (default:
+                ``t2_``).
+
+:short_url: The URL used to generate short links on the Reddit instance
+            (default: https://redd.it).
+
+:submission_kind: The type prefix for submissions on the Reddit instance
+                  (default: ``t3_``).
+
+:subreddit_kind: The type prefix for subreddits on the Reddit instance
+                 (default: ``t5_``).
+
+.. _custom_options:
+
+Custom Configuration Options
+----------------------------
+
+Your application can utilize PRAW's configuration system in order to provide
+its own custom settings.
+
+For instance you might want to add an ``app_debugging: true`` option to your
+application's ``praw.ini`` file. To retreive the value of this custom option
+from an instance of :class:`.Reddit` you can execute:
+
+.. code-block:: python
+
+   reddit.config.custom['app_debugging']
+
+.. note:: Custom PRAW configuration environment variables are not
+          supported. You can directly access environment variables via
+          ``os.getenv``.

docs/index.rst

@@ -34,6 +34,7 @@ PRAW's documetnation is organized into the following sections:
    :caption: Tutorials
 
    tutorials/comments.rst
+   tutorials/refresh_token.rst
    tutorials/reply_bot.rst
 
 .. _package_info:

docs/tutorials/refresh_token.rst

@@ -0,0 +1,11 @@
+.. _refresh_token:
+
+Obtaining a Refresh Token
+=========================
+
+The following program can be used to obtain a refresh token with the desired
+scopes. Such a token can be used in conjunction with the ``refresh_token``
+keyword argument using in initializing an instance of :class:`~praw.Reddit`.
+
+.. include:: ../examples/obtain_refresh_token.py
+   :code: python

praw/config.py

@@ -63,10 +63,9 @@ def __init__(self, site_name, **settings):
         self._settings = settings
         self.custom = dict(Config.CONFIG.items(site_name), **settings)
 
-        self.client_id = self.client_secret = self.http_proxy = None
-        self.https_proxy = self.oauth_url = self.reddit_url = None
-        self.refresh_token = self.redirect_uri = self.password = None
-        self.user_agent = self.username = None
+        self.client_id = self.client_secret = self.oauth_url = None
+        self.reddit_url = self.refresh_token = self.redirect_uri = None
+        self.password = self.user_agent = self.username = None
 
         self._initialize_attributes()