Update docs.

Author: stephrdev

README.rst

@@ -1,12 +1,14 @@
 =========
 Cacheback
 =========
+
 ----------------------------------------
 Asynchronous cache refreshing for Django
 ----------------------------------------
 
 What does this library do?
 --------------------------
+
 It's an extensible caching library that refreshes stale cache items
 asynchronously using a Celery_ or rq_ task (utilizing django-rq). The key
 idea being that it's better to serve a stale item (and populate the cache
@@ -22,33 +24,41 @@ cache - which can be a significant performance boost.
 A corollary of this technique is that cache hammering can be handled simply and
 elegantly, avoiding sudden surges of expensive reads when a cached item becomes stale.
 
+
 Do you have good docs?
 ----------------------
+
 Yup - `over on readthedocs.org`_.
 
 .. _`over on readthedocs.org`: http://django-cacheback.readthedocs.org/en/latest/
 
-Do you support Python 3?
-------------------------
-Python 3.4, 3.5, 3.6, 3.7 and PyPy3 are supported.
 
-Django versions 1.8 to 3.0 are supported.
+Supported versions
+------------------
+
+Python 3.6+ is supported. Django 2.0+ is supported.
+
 
 Do you have tests?
 ------------------
+
 You betcha!
 
 .. image:: https://secure.travis-ci.org/codeinthehole/django-cacheback.png
     :target: https://travis-ci.org/#!/codeinthehole/django-cacheback
 
+
 Can I use this in my project?
 -----------------------------
+
 Probably - subject to the `MIT license`_.
 
 .. _`MIT license`: https://github.com/codeinthehole/django-cacheback/blob/master/LICENSE
 
+
 I want to contribute!
 ---------------------
+
 Brilliant!  Here are the `contributing guidelines`_.
 
 .. _`contributing guidelines`: http://django-cacheback.readthedocs.org/en/latest/contributing.html

docs/advanced.rst

@@ -2,7 +2,7 @@ Advanced usage
 --------------
 
 Three thresholds for cache invalidation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It's possible to employ three threshold times to control cache behaviour:
 

docs/api.rst

@@ -2,20 +2,21 @@
 API
 ===
 
-The main class is ``cacheback.base.Job``.  The methods that are intended to be called from client code are:
+The main class is ``cacheback.base.Job``.  The methods that are intended to be
+called from client code are:
 
 .. autoclass:: cacheback.base.Job
     :members: get, invalidate, delete
 
 It has some class properties than can be used to configure simple behaviour:
 
 .. autoclass:: cacheback.base.Job
-    :members: lifetime, refresh_timeout, cache_alias, fetch_on_miss, fetch_on_stale_threshold
+    :members: lifetime, refresh_timeout, cache_alias, fetch_on_miss, fetch_on_stale_threshold, task_options
 
 There are also several methods intended to be overridden and customised:
 
 .. autoclass:: cacheback.base.Job
-    :members: key, fetch, expiry, should_missing_item_be_fetched_synchronously, should_stale_item_be_fetched_synchronously, empty, key, prepare_args, prepare_kwargs, timeout, process_result 
+    :members: key, fetch, expiry, should_missing_item_be_fetched_synchronously, should_stale_item_be_fetched_synchronously, empty, key, prepare_args, prepare_kwargs, timeout, process_result
 
 
 Queryset jobs
@@ -30,23 +31,22 @@ subclassing but rather take the model class as a ``__init__`` parameter.
 .. autoclass:: cacheback.jobs.QuerySetGetJob
     :members:
 
+
 Example usage:
 
 .. sourcecode:: python
- 
+
     from django.contrib.auth import models
     from django.shortcuts import render
     from cacheback.jobs import QuerySetGetJob, QuerySetFilterJob
 
     def user_detail(request, username):
         user = QuerySetGetJob(models.User).get(username=username)
-        return render(request, 'user.html',
-                      {'user': user})
+        return render(request, 'user.html', {'user': user})
 
     def staff(request):
         staff = QuerySetFilterJob(models.User).get(is_staff=True)
-        return render(request, 'staff.html',
-                      {'users': staff})
+        return render(request, 'staff.html', {'users': staff})
 
 These classes are helpful for simple ORM reads but won't be suitable for more
 complicated queries where ``filter`` is chained together with ``exclude``.

docs/contributing.rst

@@ -2,52 +2,34 @@
 Contributing
 ============
 
-Start by cloning the repo, creating a virtualenv and running::
+Make sure to have `poetry` installed. Then, start by cloning the repo,
+and installing the dependencies:
 
-    $ make install
+    $ pip install poetry  # if not already installed
+    $ cd <repository directory>
+    $ poetry install
 
-to install the testing dependencies.
 
 Running tests
 =============
 
 Use::
 
-    $ py.test
+    # only runs actual tests
+    $ make pytests
 
-or generate coverage report::
+or::
 
-    $ py.test --cov
+    # runs tests but also linters like black, isort and flake8
+    $ make tests
 
-or use Tox with::
 
-    $ tox
-
-to test all Python/Django combinations.
-
-Sandbox VM
-==========
-
-There is a ``VagrantFile`` for setting up a sandbox VM where you can play around
-with the functionality.  Bring up the Vagrant box::
-
-    $ vagrant up
+To generate html coverage::
 
-This may take a while but will set up a Ubuntu Precise64 VM with RabbitMQ
-installed.  You can then SSH into the machine::
+    $ make coverage-html
 
-    $ vagrant ssh
-    $ cd /vagrant/sandbox
 
-You can now decide to run the Celery implementation::
+Finally, you can also use tox to run tests against
+all supported Django and Python versions::
 
-    $ honcho -f Procfile.celery start
-
-Or you can run the RQ implementation::
-
-    $ honcho -f Procfile.rq start
-
-The above commands will start a Django runserver and the selected task worker.
-The dummy site will be available at ``http://localhost:8080`` on your host
-machine.  There are some sample views in ``sandbox/dummyapp/views.py`` that
-exercise django-cacheback.
+    $ tox

docs/index.rst

@@ -1,8 +1,3 @@
-.. django-async-cache documentation master file, created by
-   sphinx-quickstart on Mon Jul 30 21:40:46 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 ================
 Django Cacheback
 ================
@@ -17,7 +12,7 @@ synchronously.
 .. _rq: http://python-rq.org/
 
 Using this library, you can rework your views so that all reads are from
-cache - which can be a significant performance boost.  
+cache - which can be a significant performance boost.
 
 A corollary of this technique is that cache stampedes can be easily avoided,
 avoiding sudden surges of expensive reads when cached items becomes stale.
@@ -37,24 +32,24 @@ Consider a view for showing a user's tweets:
     from myproject.twitter import fetch_tweets
 
     def show_tweets(request, username):
-        return render(request, 'tweets.html', 
+        return render(request, 'tweets.html',
                       {'tweets': fetch_tweets(username)})
 
 This works fine but the ``fetch_tweets`` function involves a HTTP round-trip and
-is slow.  
+is slow.
 
 Performance can be improved by using Django's `low-level cache API`_:
 
 .. _`low-level cache API`: https://docs.djangoproject.com/en/dev/topics/cache/?from=olddocs#the-low-level-cache-api
-        
+
 .. sourcecode:: python
 
     from django.shortcuts import render
     from django.cache import cache
     from myproject.twitter import fetch_tweets
 
     def show_tweets(request, username):
-        return render(request, 'tweets.html', 
+        return render(request, 'tweets.html',
                       {'tweets': fetch_cached_tweets(username)})
 
     def fetch_cached_tweets(username):
@@ -88,7 +83,7 @@ cache asynchronously instead of during the request/response cycle:
     from myproject.tasks import update_tweets
 
     def show_tweets(request, username):
-        return render(request, 'tweets.html', 
+        return render(request, 'tweets.html',
                       {'tweets': fetch_cached_tweets(username)})
 
     def fetch_cached_tweets(username):
@@ -116,7 +111,7 @@ where the ``myproject.tasks.update_tweets`` task is implemented as:
     def update_tweets(username, ttl):
         tweets = fetch_tweets(username)
         now = datetime.datetime.now()
-        cache.set(username, (tweets, now+ttl), 2592000) 
+        cache.set(username, (tweets, now+ttl), 2592000)
 
 Some things to note:
 
@@ -147,7 +142,7 @@ Here's the same functionality implemented using a django-cacheback decorator:
     from cacheback.decorators import cacheback
 
     def show_tweets(request, username):
-        return render(request, 'tweets.html', 
+        return render(request, 'tweets.html',
                       {'tweets': cacheback(60*15, fetch_on_miss=False)(fetch_tweets)(username)})
 
 Here the decorator simply wraps the ``fetch_tweets`` function - nothing else is
@@ -206,4 +201,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-