Move backend docs to user guide, separate from API reference docs

7 files changed, 43 insertions, 8 deletions

diff --git a/requests_cache/backends/__init__.py b/requests_cache/backends/__init__.py
index 4051d14..250be7e 100644
--- a/requests_cache/backends/__init__.py
+++ b/requests_cache/backends/__init__.py
@@ -73,6 +73,8 @@ def init_backend(cache_name: str, backend: BackendSpecifier = None, **kwargs) ->
             backend.cache_name = cache_name
         return backend
     # If no backend is specified, use SQLite as default, unless the environment doesn't support it
+    # TODO: Deprecate fallback to memory?
+    #   Unsupported SQLite is a rare case, and should probably be handled by the user instead.
     elif not backend:
         sqlite_supported = issubclass(BACKEND_CLASSES['sqlite'], BaseCache)
         backend = 'sqlite' if sqlite_supported else 'memory'
diff --git a/requests_cache/backends/dynamodb.py b/requests_cache/backends/dynamodb.py
index 260a078..5f03523 100644
--- a/requests_cache/backends/dynamodb.py
+++ b/requests_cache/backends/dynamodb.py
@@ -1,3 +1,9 @@
+"""DynamoDB cache backend. For usage details, see :ref:`Backends: DynamoDB <dynamodb>`.
+
+.. automodsumm:: requests_cache.backends.dynamodb
+   :classes-only:
+   :nosignatures:
+"""
 from typing import Dict, Iterable
 
 import boto3
@@ -10,7 +16,7 @@ from . import BaseCache, BaseStorage
 
 
 class DynamoDbCache(BaseCache):
-    """DynamoDB cache backend
+    """DynamoDB cache backend.
 
     Args:
         table_name: DynamoDB table name
@@ -59,6 +65,7 @@ class DynamoDbDict(BaseStorage):
         self.connection = connection or boto3.resource('dynamodb', **connection_kwargs)
         self.namespace = namespace
 
+        # TODO: Create default table as on-demand instead of provisioned?
         try:
             self.connection.create_table(
                 AttributeDefinitions=[
diff --git a/requests_cache/backends/filesystem.py b/requests_cache/backends/filesystem.py
index 021204b..f633a22 100644
--- a/requests_cache/backends/filesystem.py
+++ b/requests_cache/backends/filesystem.py
@@ -1,3 +1,9 @@
+"""Filesystem cache backend. For usage details, see :ref:`Backends: Filesystem <filesystem>`.
+
+.. automodsumm:: requests_cache.backends.filesystem
+   :classes-only:
+   :nosignatures:
+"""
 from contextlib import contextmanager
 from os import makedirs
 from pathlib import Path
@@ -12,7 +18,7 @@ from .sqlite import AnyPath, SQLiteDict, get_cache_path
 
 
 class FileCache(BaseCache):
-    """Filesystem backend.
+    """Filesystem cache backend.
 
     Args:
         cache_name: Base directory for cache files
diff --git a/requests_cache/backends/gridfs.py b/requests_cache/backends/gridfs.py
index 0e0e5ee..20c2b06 100644
--- a/requests_cache/backends/gridfs.py
+++ b/requests_cache/backends/gridfs.py
@@ -1,3 +1,9 @@
+"""GridFS cache backend. For usage details, see :ref:`Backends: GridFS <gridfs>` and :ref:`Backends: MongoDB <mongodb>`.
+
+.. automodsumm:: requests_cache.backends.gridfs
+   :classes-only:
+   :nosignatures:
+"""
 from logging import getLogger
 from threading import RLock
 
@@ -15,10 +21,6 @@ logger = getLogger(__name__)
 class GridFSCache(BaseCache):
     """GridFS cache backend.
 
-    Example:
-
-        >>> session = CachedSession('http_cache', backend='gridfs')
-
     Args:
         db_name: Database name
         connection: :py:class:`pymongo.MongoClient` object to reuse instead of creating a new one
diff --git a/requests_cache/backends/mongodb.py b/requests_cache/backends/mongodb.py
index 2e3b116..9605988 100644
--- a/requests_cache/backends/mongodb.py
+++ b/requests_cache/backends/mongodb.py
@@ -1,3 +1,9 @@
+"""MongoDB cache backend. For usage details, see :ref:`Backends: MongoDB <mongodb>`.
+
+.. automodsumm:: requests_cache.backends.mongodb
+   :classes-only:
+   :nosignatures:
+"""
 from datetime import timedelta
 from logging import getLogger
 from typing import Iterable, Mapping, Optional, Union
@@ -14,7 +20,7 @@ logger = getLogger(__name__)
 
 
 class MongoCache(BaseCache):
-    """MongoDB cache backend
+    """MongoDB cache backend.
 
     Args:
         db_name: Database name
diff --git a/requests_cache/backends/redis.py b/requests_cache/backends/redis.py
index a5c0675..d79af35 100644
--- a/requests_cache/backends/redis.py
+++ b/requests_cache/backends/redis.py
@@ -1,3 +1,9 @@
+"""Redis cache backend. For usage details, see :ref:`Backends: Redis <redis>`.
+
+.. automodsumm:: requests_cache.backends.redis
+   :classes-only:
+   :nosignatures:
+"""
 from logging import getLogger
 from typing import Iterable
 
@@ -13,7 +19,7 @@ logger = getLogger(__name__)
 # TODO: TTL tests
 # TODO: Option to set a different (typically longer) TTL than expire_after, like MongoCache
 class RedisCache(BaseCache):
-    """Redis cache backend
+    """Redis cache backend.
 
     Args:
         namespace: Redis namespace
diff --git a/requests_cache/backends/sqlite.py b/requests_cache/backends/sqlite.py
index baff2f8..fa75848 100644
--- a/requests_cache/backends/sqlite.py
+++ b/requests_cache/backends/sqlite.py
@@ -1,3 +1,9 @@
+"""SQLite cache backend. For usage details, see :ref:`Backends: SQLite <sqlite>`.
+
+.. automodsumm:: requests_cache.backends.sqlite
+   :classes-only:
+   :nosignatures:
+"""
 import sqlite3
 import threading
 from contextlib import contextmanager