Updating docs

[ci skip]

docs/_static/custom.css

@@ -11,3 +11,13 @@
         margin-right: 115px !important;
     }
 }
+
+.literal {
+    background: #f5f5f5;
+    padding: 2px 3px 3px;
+    border: 1px solid #ccc;
+    color: #11729B;
+    -webkit-border-radius: 3px;
+    border-radius: 3px;
+    margin: 0 3px;
+}

docs/usage/advanced_usage.rst

@@ -3,15 +3,17 @@
 Advanced Usage
 ==============
 
-This section will cover how to use Twython and interact with some a little more advanced API calls
+This section will cover how to use Twython and interact with some more advanced API calls
 
-Before you make any API calls, make sure you :ref:`authenticated <starting-out>` the user!
+Before you make any API calls, make sure you :ref:`authenticated the user <starting-out>` (or :ref:`app <oauth2>`)!
 
 .. note:: All sections on this page will assume you're using a Twython instance
 
 *******************************************************************************
 
-Create a Twython instance with your application keys and the users OAuth tokens::
+Create a Twython instance with your application keys and the users OAuth tokens
+
+.. code-block:: python
 
     from twython import Twython
     twitter = Twython(APP_KEY, APP_SECRET
@@ -22,17 +24,17 @@ Updating Status with Image
 
 Documentation: https://dev.twitter.com/docs/api/1.1/get/account/verify_credentials
 
-::
+.. code-block:: python
 
     photo = open('/path/to/file/image.jpg', 'rb')
     twitter.update_status_with_media(status='Checkout this cool image!', media=photo)
 
 Posting a Status with an Editing Image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
     This example resizes an image
 
-::
+.. code-block:: python
 
     # Assume you are working with a JPEG
 
@@ -63,7 +65,7 @@ So, if you're pretty into Python, you probably know about `generators <http://do
 
 That being said, Twython offers a generator for search results and can be accessed by using the following code:
 
-::
+.. code-block:: python
 
     search = twitter.search_gen('python')
     for result in search:
@@ -78,7 +80,7 @@ Twython uses the `requests <http://python-requests.org>`_ library to make API ca
 
 Here is an example of sending custom headers to a Twitter API request:
 
-::
+.. code-block:: python
 
     from twython import Twython
 
@@ -94,7 +96,7 @@ Here is an example of sending custom headers to a Twitter API request:
 
 Here is an example of sending the request through proxies:
 
-::
+.. code-block:: python
 
     from twython import Twython
 
@@ -111,7 +113,7 @@ Here is an example of sending the request through proxies:
 
 or both (and set a timeout variable):
 
-::
+.. code-block:: python
 
     from twython import Twython
 

docs/usage/basic_usage.rst

@@ -5,7 +5,7 @@ Basic Usage
 
 This section will cover how to use Twython and interact with some basic Twitter API calls
 
-Before you make any API calls, make sure you :ref:`authenticated <starting-out>` the user!
+Before you make any API calls, make sure you :ref:`authenticated the user <oauth1>` (or :ref:`app <oauth2>`)!
 
 .. note:: All sections on this page will assume you're using a Twython instance
 
@@ -17,7 +17,9 @@ Authenticated Calls
 OAuth 1
 ~~~~~~~
 
-Create a Twython instance with your application keys and the users OAuth tokens::
+Create a Twython instance with your application keys and the users OAuth tokens
+
+.. code-block:: python
 
     from twython import Twython
     twitter = Twython(APP_KEY, APP_SECRET
@@ -28,7 +30,7 @@ User Information
 
 Documentation: https://dev.twitter.com/docs/api/1.1/get/account/verify_credentials
 
-::
+.. code-block:: python
 
     twitter.verify_credentials()
 
@@ -37,7 +39,7 @@ Authenticated Users Home Timeline
 
 Documentation: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline
 
-::
+.. code-block:: python
 
     twitter.get_home_timeline()
 
@@ -48,7 +50,7 @@ This method makes use of dynamic arguments, :ref:`read more about them <dynamica
 
 Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update
 
-::
+.. code-block:: python
 
     twitter.update_status(status='See how easy using Twython is!')
 
@@ -56,7 +58,9 @@ Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update
 OAuth 2
 ~~~~~~~
 
-Create a Twython instance with your application key and access token::
+Create a Twython instance with your application key and access token
+
+.. code-block:: python
 
     from twython import Twython
     twitter = Twython(APP_KEY, access_token=ACCESS_TOKEN)
@@ -70,7 +74,7 @@ Searching
 
 Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets
 
-::
+.. code-block:: python
 
     twitter.search(q='python')
 
@@ -78,7 +82,10 @@ Documentation: https://dev.twitter.com/docs/api/1.1/get/search/tweets
 
 .. important:: To help explain :ref:`dynamic function arguments <dynamicfunctionarguments>` a little more, you can see that the previous call used the keyword argument ``q``, that is because Twitter specifies in their `search documentation <https://dev.twitter.com/docs/api/1.1/get/search/tweets>`_ that the search call accepts the parameter "q". You can pass mutiple keyword arguments. The search documentation also specifies that the call accepts the parameter "result_type"
 
-::
+.. code-block:: python
 
     twitter.search(q='python', result_type='popular')
 
+*******************************************************************************
+
+So, now, you're pretty well versed on making authenticated calls to Twitter using Twython. Check out the :ref:`advanced usage <advanced-usage>` section, for some functions that may be a little more complicated.

docs/usage/install.rst

@@ -10,11 +10,15 @@ Information on how to properly install Twython
 Pip or Easy Install
 -------------------
 
-Install Twython via `pip <http://www.pip-installer.org/>`_::
+Install Twython via `pip <http://www.pip-installer.org/>`_
+
+.. code-block:: bash
 
     $ pip install twython
 
-or, with `easy_install <http://pypi.python.org/pypi/setuptools>`_::
+or, with `easy_install <http://pypi.python.org/pypi/setuptools>`_
+
+.. code-block:: bash
 
     $ easy_install twython
 
@@ -26,19 +30,27 @@ Source Code
 
 Twython is actively maintained on GitHub
 
-Feel free to clone the repository::
+Feel free to clone the repository
+
+.. code-block:: bash
 
     git clone git://github.com/ryanmcgrath/twython.git
 
-`tarball <https://github.com/ryanmcgrath/twython/tarball/master>`_::
+`tarball <https://github.com/ryanmcgrath/twython/tarball/master>`_
+
+.. code-block:: bash
 
     $ curl -OL https://github.com/ryanmcgrath/twython/tarball/master
 
-`zipball <https://github.com/ryanmcgrath/twython/tarball/master>`_::
+`zipball <https://github.com/ryanmcgrath/twython/tarball/master>`_
+
+.. code-block:: bash
 
     $ curl -OL https://github.com/ryanmcgrath/twython/zipball/master
 
-Now that you have the source code, install it into your site-packages directory::
+Now that you have the source code, install it into your site-packages directory
+
+.. code-block:: bash
 
     $ python setup.py install
 

docs/usage/starting_out.rst

@@ -23,7 +23,7 @@ Twython offers support for both OAuth 1 and OAuth 2 authentication.
 
 The difference:
 
-- :ref:`OAuth 1 <oauth1>` is for user authenticated calls (tweeting, following people, sneding DMs, etc.)
+- :ref:`OAuth 1 <oauth1>` is for user authenticated calls (tweeting, following people, sending DMs, etc.)
 - :ref:`OAuth 2 <oauth2>` is for application authenticated calls (when you don't want to authenticate a user and make read-only calls to Twitter, i.e. searching, reading a public users timeline)
 
 .. _oauth1:
@@ -33,7 +33,9 @@ OAuth 1 (User Authentication)
 
 .. important:: Again, if your web app is planning on using interacting with users, this **IS** the authentication type for you. If you're not interested in authenticating a user and plan on making read-only calls, check out the :ref:`OAuth 2 <oauth2>` section.
 
-First, you'll want to import Twython::
+First, you'll want to import Twython
+
+.. code-block:: python
 
     from twython import Twython
 
@@ -42,7 +44,7 @@ Now, you'll want to create a Twython instance with your ``Consumer Key`` and ``C
 Obtain Authorization URL
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     APP_KEY = 'YOUR_APP_KEY'
     APP_SECET = 'YOUR_APP_SECRET'
@@ -50,11 +52,15 @@ Obtain Authorization URL
     twitter = Twython(APP_KEY, APP_SECRET)
     auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback')
 
-From the ``auth`` variable, save the ``oauth_token_secret`` for later use. In Django or other web frameworks, you might want to store it to a session variable::
+From the ``auth`` variable, save the ``oauth_token_secret`` for later use. In Django or other web frameworks, you might want to store it to a session variable
+
+.. code-block:: python
 
     OAUTH_TOKEN_SECRET = auth['oauth_token_secret']
 
-Send the user to the authentication url, you can obtain it by accessing::
+Send the user to the authentication url, you can obtain it by accessing
+
+.. code-block:: python
 
     auth['auth_url']
 
@@ -66,19 +72,24 @@ After they authorize your application to access some of their account details, t
 You'll want to extract the ``oauth_token`` and ``oauth_verifier`` from the url.
 
 Django example:
-::
+
+.. code-block:: python
 
     OAUTH_TOKEN = request.GET['oauth_token']
     oauth_verifier = request.GET['oauth_verifier']
 
-Now that you have the ``oauth_token`` and ``oauth_verifier`` stored to variables, you'll want to create a new instance of Twython and grab the final user tokens::
+Now that you have the ``oauth_token`` and ``oauth_verifier`` stored to variables, you'll want to create a new instance of Twython and grab the final user tokens
+
+.. code-block:: python
 
     twitter = Twython(APP_KEY, APP_SECRET,
                       OAUTH_TOKEN, OAUTH_TOKEN_SECRET)
 
     final_step = twitter.get_authorized_tokens(oauth_verifier)
 
-Once you have the final user tokens, store them in a database for later use!::
+Once you have the final user tokens, store them in a database for later use!
+
+.. code-block:: python
 
     OAUTH_TOKEN = final_step['oauth_token']
     OAUTH_TOKEN_SECERT = final_step['oauth_token_secret']
@@ -93,14 +104,16 @@ OAuth 2 (Application Authentication)
 OAuth 2 authentication is 100x easier than OAuth 1.
 Let's say you *just* made your application and have your ``Consumer Key`` and ``Consumer Secret``
 
-First, you'll want to import Twython::
+First, you'll want to import Twython
+
+.. code-block:: python
 
     from twython import Twython
 
 Obtain an OAuth 2 Access Token
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     APP_KEY = 'YOUR_APP_KEY'
     APP_SECET = 'YOUR_APP_SECRET'
@@ -108,12 +121,12 @@ Obtain an OAuth 2 Access Token
     twitter = Twython(APP_KEY, APP_SECRET, oauth_version=2)
     ACCESS_TOKEN = twitter.obtain_access_token()
 
-    # Save ACCESS_TOKEN in a database or something for later use!
+Save ``ACCESS_TOKEN`` in a database or something for later use!
 
 Use the Access Token
 ^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
     APP_KEY = 'YOUR_APP_KEY'
     ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'

docs/usage/streaming_api.rst

@@ -16,13 +16,13 @@ Setting Up Your Streamer
 
 Make sure you import ``TwythonStreamer``
 
-::
+.. code-block:: python
 
     from twython import TwythonStreamer
 
 Now set up how you want to handle the signals.
 
-::
+.. code-block:: python
 
     class MyStreamer(TwythonStreamer):
         def on_success(self, data):
@@ -41,7 +41,7 @@ More signals that you can extend on can be found in the Developer Interface sect
 Filtering Public Statuses
 -------------------------
 
-::
+.. code-block:: python
 
     stream = MyStreamer(APP_KEY, APP_SECRET,
                         OAUTH_TOKEN, OAUTH_TOKEN_SECRET)