Update docs, doc dependencies, changelog, and contributors

Also:
Restrict redis-py to <4.2, which breaks parameter forwarding on python 3.7 and 3.8

6 files changed, 45 insertions, 27 deletions

diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
index 630efd2..18e07c8 100644
--- a/docs/_templates/module.rst_t
+++ b/docs/_templates/module.rst_t
@@ -12,3 +12,4 @@
    :undoc-members:
    :inherited-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/conf.py b/docs/conf.py
index 55b35a7..ed48e1b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,5 +1,4 @@
 # requests-cache documentation build configuration file
-import logging
 import os
 import sys
 from os.path import abspath, dirname, join
@@ -15,7 +14,7 @@ TEMPLATE_DIR = join(PROJECT_DIR, 'docs', '_templates')
 
 # General information about the project.
 project = 'requests-cache'
-needs_sphinx = '3.0'
+needs_sphinx = '4.0'
 master_doc = 'index'
 source_suffix = ['.rst', '.md']
 version = release = __version__
@@ -83,8 +82,8 @@ copybutton_prompt_is_regexp = True
 # Generate labels in the format <page>:<section>
 autosectionlabel_prefix_document = True
 
-# Use sphinx_autodoc_typehints extension instead of autodoc's built-in type hints
-autodoc_typehints = 'none'
+# Move type hint info to function description instead of signature
+autodoc_typehints = 'description'
 always_document_param_types = True
 
 # Use apidoc to auto-generate rst sources
@@ -137,13 +136,8 @@ def setup(app):
 def patch_automodapi(app):
     """Monkey-patch the automodapi extension to exclude imported members:
     https://github.com/astropy/sphinx-automodapi/blob/master/sphinx_automodapi/automodsumm.py#L135
-
-    Also patches an unreleased fix for Sphinx 4 compatibility:
-    https://github.com/astropy/sphinx-automodapi/pull/129
     """
     from sphinx_automodapi import automodsumm
-    from sphinx_automodapi.automodsumm import Automodsumm
     from sphinx_automodapi.utils import find_mod_objs
 
     automodsumm.find_mod_objs = lambda *args: find_mod_objs(args[0], onlylocals=True)
-    Automodsumm.warn = lambda *args: logging.getLogger('sphinx_automodapi').warn(*args)
diff --git a/docs/reference.md b/docs/reference.md
index f5a1b8a..9d784b9 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -11,19 +11,24 @@ from requests_cache import CachedSession, RedisCache, json_serializer
 ```
 :::
 
+## Primary Modules
+The following modules include the majority of the API relevant for most users:
+
 ```{toctree}
-:maxdepth: 1
+:maxdepth: 2
 session
 modules/requests_cache.patcher
-```
-```{toctree}
-:maxdepth: 2
 modules/requests_cache.backends
 modules/requests_cache.models
-modules/requests_cache.serializers
+modules/requests_cache.settings
 ```
+
+## Secondary Modules
+The following modules are mainly for internal use, and are relevant for contributors and advanced users:
 ```{toctree}
-:maxdepth: 1
+:maxdepth: 2
 modules/requests_cache.cache_keys
 modules/requests_cache.cache_control
+modules/requests_cache.expiration
+modules/requests_cache.serializers
 ```
diff --git a/docs/user_guide/advanced_requests.md b/docs/user_guide/advanced_requests.md
index 1a18939..fcd5a6c 100644
--- a/docs/user_guide/advanced_requests.md
+++ b/docs/user_guide/advanced_requests.md
@@ -14,7 +14,7 @@ It can be used, for example, for request throttling:
 >>> import time
 >>> import requests
 >>> from requests_cache import CachedSession
->>>
+
 >>> def make_throttle_hook(timeout=1.0):
 >>>     """Make a request hook function that adds a custom delay for non-cached requests"""
 >>>     def hook(response, *args, **kwargs):
@@ -23,7 +23,7 @@ It can be used, for example, for request throttling:
 >>>             time.sleep(timeout)
 >>>         return response
 >>>     return hook
->>>
+
 >>> session = CachedSession()
 >>> session.hooks['response'].append(make_throttle_hook(0.1))
 >>> # The first (real) request will have an added delay
@@ -42,7 +42,7 @@ the original streamed response:
 :class: toggle
 ```python
 >>> from requests_cache import CachedSession
->>>
+
 >>> session = CachedSession()
 >>> for i in range(2):
 ...     response = session.get('https://httpbin.org/stream/20', stream=True)
diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 5c81ef0..24b9c8a 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -37,7 +37,7 @@ Examples:
 >>> session = CachedSession(expire_after=timedelta(days=30))
 
 >>> # Update an existing session to disable expiration (i.e., store indefinitely)
->>> session.expire_after = -1
+>>> session.settings.expire_after = -1
 
 >>> # Disable caching by default, unless enabled by other settings
 >>> session = CachedSession(expire_after=0)
@@ -61,11 +61,11 @@ frequently, another that changes infrequently, and another that never changes. E
 
 **Notes:**
 - `urls_expire_after` should be a dict in the format `{'pattern': expire_after}`
-- `expire_after` accepts the same types as `CachedSession.expire_after`
+- `expire_after` accepts the same types as `CachedSession.settings.expire_after`
 - Patterns will match request **base URLs without the protocol**, so the pattern `site.com/resource/`
   is equivalent to `http*://site.com/resource/**`
 - If there is more than one match, the first match will be used in the order they are defined
-- If no patterns match a request, `CachedSession.expire_after` will be used as a default
+- If no patterns match a request, `CachedSession.settings.expire_after` will be used as a default
 
 (request-errors)=
 ## Expiration and Error Handling
diff --git a/docs/user_guide/general.md b/docs/user_guide/general.md
index 2932a25..7047f04 100644
--- a/docs/user_guide/general.md
+++ b/docs/user_guide/general.md
@@ -9,7 +9,7 @@ There are two main ways of using requests-cache:
 Basic usage looks like this:
 ```python
 >>> from requests_cache import CachedSession
->>>
+
 >>> session = CachedSession()
 >>> session.get('http://httpbin.org/get')
 ```
@@ -41,7 +41,7 @@ cases, you can use {py:func}`.install_cache` to add caching to all `requests` fu
 ```python
 >>> import requests
 >>> import requests_cache
->>>
+
 >>> requests_cache.install_cache()
 >>> requests.get('http://httpbin.org/get')
 ```
@@ -81,13 +81,31 @@ requests-cache is currently installed with {py:func}`.is_installed`.
 
 (monkeypatch-issues)=
 ### Patching Limitations & Potential Issues
-Like any other utility that uses monkey-patching, there are some scenarios where you won't want to
-use {py:func}`.install_cache`:
+There are some scenarios where patching `requests` with {py:func}`.install_cache` is not ideal:
 - When using other libraries that patch {py:class}`requests.Session`
 - In a multi-threaded or multiprocess application
 - In a library that will be imported by other libraries or applications
 - In a larger application that makes requests in several different modules, where it may not be
   obvious what is and isn't being cached
 
-In any of these cases, consider using {py:class}`.CachedSession`, the {py:func}`.enabled`
-contextmanager, or {ref}`selective-caching`.
+In these cases, consider using {py:class}`.CachedSession` instead.
+
+(settings)=
+## Settings
+There are a number of settings that affect cache behavior, which are covered in more detail in the following sections:
+* {ref}`expiration`
+* {ref}`filtering`
+* {ref}`matching`
+
+These can all be passed as keyword arguments to {py:class}`.CachedSession` or
+{py:func}`.install_cache`. When using a session object, these can also be safely modified at any
+time via {py:attr}`.CachedSession.settings`. For example:
+```python
+>>> from requests_cache import CachedSession
+
+>>> session = CachedSession()
+>>> session.settings.expire_after = 360
+>>> session.settings.stale_if_error = True
+```
+
+Note that this does **not** include backend and serializer settings, which cannot be changed after initialization.