Merge pull request #96 from sh4nks/improve-docs

Improve documentation
pallets-eco · Mar 6, 2019 · ca5848d · ca5848d
2 parents 85db169 + d39174e
commit ca5848d
Show file tree

Hide file tree

Showing 5 changed files with 167 additions and 21 deletions.
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,83 @@
+API
+===
+
+This section contains the API documentation of the Flask-Caching extension and
+lists the backends which are supported out of the box.
+The `Configuration <index.html#configuring-flask-caching>`_ section explains
+how the backends can be used.
+
+
+.. module:: flask_caching
+
+Cache API
+---------
+
+.. autoclass:: Cache
+   :members: init_app, get, set, add, delete, get_many, set_many, delete_many,
+             clear, cached, memoize, delete_memoized, delete_memoized_verhash
+
+
+Backends
+--------
+
+.. module:: flask_caching.backends
+
+BaseCache
+`````````
+
+.. autoclass:: flask_caching.backends.base.BaseCache
+   :members:
+
+NullCache
+`````````
+
+.. autoclass:: NullCache
+   :members:
+
+SimpleCache
+```````````
+
+.. autoclass:: SimpleCache
+   :members:
+
+FileSystemCache
+```````````````
+
+.. autoclass:: FileSystemCache
+   :members:
+
+RedisCache
+``````````
+
+.. autoclass:: RedisCache
+   :members:
+
+RedisSentinelCache
+``````````````````
+
+.. autoclass:: RedisSentinelCache
+   :members:
+
+UWSGICache
+``````````
+
+.. autoclass:: UWSGICache
+   :members:
+
+MemcachedCache
+``````````````
+
+.. autoclass:: MemcachedCache
+   :members:
+
+SASLMemcachedCache
+``````````````````
+
+.. autoclass:: SASLMemcachedCache
+   :members:
+
+SpreadSASLMemcachedCache
+````````````````````````
+
+.. autoclass:: SpreadSASLMemcachedCache
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -53,6 +53,8 @@
 # The master toctree document.
 master_doc = 'index'
 
+autodoc_member_order = "bysource"
+
 # General information about the project.
 project = u'Flask-Caching'
 copyright = u'2016, Thadeus Burgess, Peter Justin'

diff --git a/docs/index.rst b/docs/index.rst
@@ -30,9 +30,15 @@ Cache is managed through a ``Cache`` instance::
     from flask import Flask
     from flask_caching import Cache
 
+    config = {
+        "DEBUG": True,          # some Flask specific configs
+        "CACHE_TYPE": "simple", # Flask-Caching related configs
+        "CACHE_DEFAULT_TIMEOUT": 300
+    }
     app = Flask(__name__)
-    # Check Configuring Flask-Caching section for more details
-    cache = Cache(app, config={'CACHE_TYPE': 'simple'})
+    # tell Flask to use the above defined config
+    app.config.from_mapping(config)
+    cache = Cache(app)
 
 You may also set up your ``Cache`` instance later at configuration time using
 **init_app** method::
@@ -42,8 +48,8 @@ You may also set up your ``Cache`` instance later at configuration time using
     app = Flask(__name__)
     cache.init_app(app)
 
-You may also provide an alternate configuration dictionary, useful if there will
-be multiple ``Cache`` instances each with a different backend::
+You may also provide an alternate configuration dictionary, useful if there
+will be multiple ``Cache`` instances each with a different backend::
 
     #: Method A: During instantiation of class
     cache = Cache(config={'CACHE_TYPE': 'simple'})
@@ -252,6 +258,28 @@ Here's an example script to empty your application's cache:
     data in your caching database.
 
 
+Explicitly Caching Data
+-----------------------
+
+Data can be cached explicitly by using the proxy methods like
+:meth:`Cache.set`, and :meth:`Cache.get` directly. There are many other proxy
+methods available via the :class:`Cache` class.
+
+For example:
+
+.. code-block:: python
+
+    @app.route("/html")
+    @app.route("/html/<foo>")
+    def html(foo=None):
+        if foo is not None:
+            cache.set("foo", foo)
+        bar = cache.get("foo")
+        return render_template_string(
+            "<html><body>foo cache: {{bar}}</body></html>", bar=bar
+        )
+
+
 Configuring Flask-Caching
 -------------------------
 
@@ -282,7 +310,7 @@ The following configuration values exist for Flask-Caching:
                                 * **redissentinel**: RedisSentinelCache (redis required)
                                 * **uwsgi**: UWSGICache (uwsgi required)
                                 * **memcached**: MemcachedCache (pylibmc or memcache required)
-                                * **gaememcached**: same as memcached -- backwards compatibility)
+                                * **gaememcached**: same as memcached (for backwards compatibility)
                                 * **saslmemcached**: SASLMemcachedCache (pylibmc required)
                                 * **spreadsaslmemcached**: SpreadSASLMemcachedCache (pylibmc required)
 
@@ -536,9 +564,10 @@ With this example, your ``CACHE_TYPE`` might be ``the_app.custom.pylibmccache``
 API
 ---
 
-.. autoclass:: Cache
-   :members: init_app, get, set, add, delete, get_many, set_many, delete_many,
-             clear, cached, memoize, delete_memoized, delete_memoized_verhash
+.. toctree::
+   :maxdepth: 2
+
+   api
 
 
 Additional Information

diff --git a/examples/hello.py b/examples/hello.py
@@ -1,31 +1,31 @@
 import random
 from datetime import datetime
 
-from flask import Flask, jsonify
-from flask_caching import Cache
+from flask import Flask, jsonify, render_template_string
 
+from flask_caching import Cache
 
 app = Flask(__name__)
-app.config.from_pyfile('hello.cfg')
+app.config.from_pyfile("hello.cfg")
 cache = Cache(app)
 
 
 #: This is an example of a cached view
-@app.route('/api/now')
+@app.route("/api/now")
 @cache.cached(50)
 def current_time():
     return str(datetime.now())
 
 
 #: This is an example of a cached function
-@cache.cached(key_prefix='binary')
+@cache.cached(key_prefix="binary")
 def random_binary():
     return [random.randrange(0, 2) for i in range(500)]
 
 
-@app.route('/api/get/binary')
+@app.route("/api/get/binary")
 def get_binary():
-    return jsonify({'data': random_binary()})
+    return jsonify({"data": random_binary()})
 
 
 #: This is an example of a memoized function
@@ -39,21 +39,31 @@ def _sub(a, b):
     return a - b - random.randrange(0, 1000)
 
 
-@app.route('/api/add/<int:a>/<int:b>')
+@app.route("/api/add/<int:a>/<int:b>")
 def add(a, b):
     return str(_add(a, b))
 
 
-@app.route('/api/sub/<int:a>/<int:b>')
+@app.route("/api/sub/<int:a>/<int:b>")
 def sub(a, b):
     return str(_sub(a, b))
 
 
-@app.route('/api/cache/delete')
+@app.route("/api/cache/delete")
 def delete_cache():
-    cache.delete_memoized('_add', '_sub')
-    return 'OK'
+    cache.delete_memoized("_add", "_sub")
+    return "OK"
+
+
+@app.route("/html")
+@app.route("/html/<foo>")
+def html(foo=None):
+    if foo is not None:
+        cache.set("foo", foo)
+    return render_template_string(
+        "<html><body>foo cache: {{foo}}</body></html>", foo=cache.get("foo")
+    )
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     app.run()
diff --git a/flask_caching/backends/rediscache.py b/flask_caching/backends/rediscache.py
@@ -167,6 +167,28 @@ def dec(self, key, delta=1):
 
 
 class RedisSentinelCache(RedisCache):
+    """Uses the Redis key-value store as a cache backend.
+
+    The first argument can be either a string denoting address of the Redis
+    server or an object resembling an instance of a redis.Redis class.
+
+    Note: Python Redis API already takes care of encoding unicode strings on
+    the fly.
+
+
+    :param sentinels: A list or a tuple of Redis sentinel addresses.
+    :param master: The name of the master server in a sentinel configuration.
+    :param password: password authentication for the Redis server.
+    :param db: db (zero-based numeric index) on Redis Server to connect.
+    :param default_timeout: the default timeout that is used if no timeout is
+                            specified on :meth:`~BaseCache.set`. A timeout of
+                            0 indicates that the cache never expires.
+    :param key_prefix: A prefix that should be added to all keys.
+
+    Any additional keyword arguments will be passed to
+    ``redis.sentinel.Sentinel``.
+    """
+
     def __init__(
         self,
         sentinels=None,