More docs

2 files changed, 64 insertions, 8 deletions

diff --git a/docs/index.rst b/docs/index.rst
index f4a29a5..4a1deb6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,12 @@
 Welcome to requests-cache's documentation!
 ==========================================
 
+`Requests-cache <http://pypi.python.org/pypi/requests-cache>`_
+is a transparent cache for requests_ library with persistence and async support.
+
+Source code and issue tracking at `BitBucket <https://bitbucket.org/reclosedev/requests-cache>`_.
+
+
 Contents:
 
 .. toctree::
@@ -15,7 +21,6 @@ Contents:
    api
 
 
-
 Indices and tables
 ==================
 
@@ -23,3 +28,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+.. _requests: http://docs.python-requests.org/
\ No newline at end of file
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index d8f3167..fe81d99 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -3,20 +3,29 @@
 User guide
 ==========
 
+
 Installation
 ------------
 
-Just enter in console::
+Install with pip_ or easy_install_::
 
     pip install --upgrade requests-cache
 
-Or::
+or download latest version from version control::
+
+    hg clone https://bitbucket.org/reclosedev/requests-cache
+    cd requests-cache
+    python setup.py install
 
-    easy_install -U requests-cache
+.. _pip: http://pypi.python.org/pypi/pip/
+.. _easy_install: http://pypi.python.org/pypi/setuptools
 
 Usage
 -----
 
+.. currentmodule:: requests_cache.core
+
+Just import :mod:`requests_cache` and call :func:`configure`
 ::
 
     import requests
@@ -24,11 +33,52 @@ Usage
 
     request_cache.configure()
 
+And you can just use ``requests`` to download pages, it will be cached transparently!
+
+For example following code will take only 1-2 seconds instead 10::
+
     for i in range(10):
-        r = requests.get('http://httpbin.org/delay/5')
+        requests.get('http://httpbin.org/delay/1')
+
+Cache can be configured with some options, such as cache filename, backend (sqlite, memory),
+expiration time, etc. (see :func:`requests_cache.configure() <requests_cache.core.configure>`
+for full list of options)
+
+For example, following code will configure cache stored in sqlite database format (default)
+named ``'cache.sqlite'`` with expiration set to 5 minutes::
+
+    request_cache.configure('cache.sqlite', backend='sqlite', expire_after=5)
+
+
+Transparent caching is achieved by monkey-patching ``requests`` library
+(it can be disabled, see ``monkey_patch`` argument for :func:`configure`) ,
+It is possible to undo this patch, and redo it again with :func:`undo_patch` and
+:func:`redo_patch`. But preferable way is to use :func:`requests_cache.disabled() <requests_cache.core.disabled>`
+and :func:`requests_cache.enabled <requests_cache.core.enabled>` context managers for temporary disabling and enabling caching::
+
+    with requests_cache.disabled():
+        for i in range(3):
+            print(requests.get('http://httpbin.org/ip').text)
+
+    with requests_cache.enabled():
+        for i in range(10):
+            print(requests.get('http://httpbin.org/delay/1').text)
+
+Also you can check if url is present in cache with :func:`requests_cache.has_url() <requests_cache.core.has_url>`
+and delete it with :func:`requests_cache.delete_url() <requests_cache.core.delete_url>`
+::
+
+    >>> import requests
+    >>> import requests_cache
+    >>> request_cache.configure()
+    >>> requests.get('http://httpbin.org/get')
+    >>> requests_cache.has_ulr('http://httpbin.org/get')
+    True
+    >>> requests_cache.delete_ulr('http://httpbin.org/get')
+    >>> requests_cache.has_ulr('http://httpbin.org/get')
+    False
 
-Cache can be configured with some options, see
-:func:`requests_cache.configure() <requests_cache.core.configure>` function reference.
+----------------------
 
-`requests-cache` also provides some useful functions...
+For more information see :doc:`API reference <api>`