Fix docs build.

Author: stephrdev

.editorconfig

@@ -21,3 +21,7 @@ line_length = 96
 [*.rst]
 indent_style = space
 indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2

.readthedocs.yml

@@ -0,0 +1,10 @@
+build:
+  image: latest
+
+python:
+  version: 3.8
+  pip_install: true
+  extra_requirements:
+    - docs
+    - celery
+    - rq

docs/api.rst

@@ -2,6 +2,9 @@
 API
 ===
 
+Jobs
+====
+
 The main class is ``cacheback.base.Job``.  The methods that are intended to be
 called from client code are:
 
@@ -11,11 +14,13 @@ called from client code are:
 It has some class properties than can be used to configure simple behaviour:
 
 .. autoclass:: cacheback.base.Job
+    :noindex:
     :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
+    :noindex:
     :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
 
 

docs/conf.py

@@ -19,11 +19,8 @@
 from django.conf import settings
 if not settings.configured:
     settings.configure(
-        DATABASES={
-            'default': {
-                'ENGINE': 'django.db.backends.sqlite3',
-                }
-            },
+        DATABASES={ 'default': {'ENGINE': 'django.db.backends.sqlite3'}},
+        RQ_QUEUES={},
     )
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -134,7 +131,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

docs/index.rst

@@ -32,8 +32,11 @@ 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',
-                      {'tweets': fetch_tweets(username)})
+        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.
@@ -49,8 +52,11 @@ Performance can be improved by using Django's `low-level cache API`_:
     from myproject.twitter import fetch_tweets
 
     def show_tweets(request, username):
-        return render(request, 'tweets.html',
-                      {'tweets': fetch_cached_tweets(username)})
+        return render(
+            request,
+            'tweets.html',
+            {'tweets': fetch_cached_tweets(username)}
+        )
 
     def fetch_cached_tweets(username):
         tweets = cache.get(username)
@@ -83,8 +89,11 @@ 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',
-                      {'tweets': fetch_cached_tweets(username)})
+        return render(
+            request,
+            'tweets.html',
+            {'tweets': fetch_cached_tweets(username)}
+        )
 
     def fetch_cached_tweets(username):
         item = cache.get(username)
@@ -142,8 +151,11 @@ 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',
-                      {'tweets': cacheback(60*15, fetch_on_miss=False)(fetch_tweets)(username)})
+        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
 needed.  Cacheback ships with a flexible Celery task that can run any function
@@ -185,6 +197,7 @@ Contents
 
 .. toctree::
    :maxdepth: 2
+   :glob:
 
    installation
    usage

docs/installation.rst

@@ -4,8 +4,8 @@ Installation
 
 You need to do three things:
 
-1. Install django-cacheback
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install django-cacheback
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 To install with Celery support, run::
 
@@ -19,8 +19,8 @@ After installing the package and dependencies, add ``cacheback`` to your ``INSTA
 If you want to use RQ as your task queue, you need to set ``CACHEBACK_TASK_QUEUE``
 in your settings to ``rq``.
 
-2. Install a message broker
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install a message broker
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Celery requires a message broker.  Use `Celery's tutorial`_ to help set one up.
 I recommend rabbitmq.
@@ -32,8 +32,8 @@ up the `django-rq installation guide`_ for more details.
 .. _`Celery's tutorial`: http://docs.celeryproject.org/en/latest/getting-started/first-steps-with-celery.html
 .. _`django-rq installation guide`: https://github.com/ui/django-rq#installation
 
-3. Set up a cache
-~~~~~~~~~~~~~~~~~
+Set up a cache
+~~~~~~~~~~~~~~
 
 You also need to ensure you have `a cache set up`_.  Most likely, you'll be using
 memcache so your settings will include something like::
@@ -48,7 +48,7 @@ memcache so your settings will include something like::
 .. _`a cache set up`: https://docs.djangoproject.com/en/dev/topics/cache/?from=olddocs
 
 Logging
--------
+~~~~~~~
 
 You may also want to configure logging handlers for the 'cacheback' named
 logger.  To set up console logging, use something like::

pyproject.toml

@@ -37,6 +37,7 @@ importlib-metadata = {version = "*", python = "<3.8"}
 django = ">=2"
 celery = {version = ">=4", optional = true}
 django-rq = {version = ">=2", optional = true}
+Sphinx = {version = ">=3.3.0,<4", optional = true}
 
 [tool.poetry.dev-dependencies]
 pytest = ">=6.0"
@@ -53,6 +54,7 @@ django-rq = ">=2"
 [tool.poetry.extras]
 celery = ["celery"]
 rq = ["django-rq"]
+docs = ["Sphinx"]
 
 [build-system]
 requires = ["poetry>=1.1"]