Move autosummaries to module docstrings instead of template, to make them easier to customize

11 files changed, 71 insertions, 43 deletions

diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t
index 235dc0e..630efd2 100644
--- a/docs/_templates/module.rst_t
+++ b/docs/_templates/module.rst_t
@@ -6,21 +6,9 @@
    | replace("fs", "FS")
    | e | heading
 }}
-``{{ basename }}`` module
 
-Summary
--------
-.. automodsumm:: {{ qualname }}
-   :classes-only:
-   :nosignatures:
-
-.. automodsumm:: {{ qualname }}
-   :functions-only:
-   :nosignatures:
-
-Details
--------
 .. automodule:: {{ qualname }}
-{%- for option in automodule_options %}
-   :{{ option }}:
-{%- endfor %}
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :show-inheritance:
diff --git a/docs/session.rst b/docs/session.rst
index d8b2e3f..efbf260 100644
--- a/docs/session.rst
+++ b/docs/session.rst
@@ -1,17 +1,3 @@
 Session
 =======
-
-Summary
--------
-.. automodsumm:: requests_cache.session
-   :classes-only:
-   :nosignatures:
-
-Details
--------
-.. Explicitly show inherited method docs on CachedSession instead of CachedMixin
-.. autoclass:: requests_cache.session.CachedSession
-    :show-inheritance:
-    :inherited-members:
-
-.. autoclass:: requests_cache.session.CacheMixin
+.. automodule:: requests_cache.session
diff --git a/noxfile.py b/noxfile.py
index fad58ab..872c5be 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -13,9 +13,9 @@ nox.options.reuse_existing_virtualenvs = True
 nox.options.sessions = ['lint', 'cov']
 
 LIVE_DOCS_PORT = 8181
-LIVE_DOCS_IGNORE = ['*.pyc', '*.tmp', '**/modules/*']
+LIVE_DOCS_IGNORE = ['*.pyc', '*.tmp']
 LIVE_DOCS_WATCH = ['requests_cache', 'examples']
-CLEAN_DIRS = ['dist', 'build', join('docs', '_build'), join('docs', 'modules')]
+CLEAN_DIRS = ['dist', 'build', join('docs', '_build')]
 
 UNIT_TESTS = join('tests', 'unit')
 INTEGRATION_TESTS = join('tests', 'integration')
diff --git a/requests_cache/backends/__init__.py b/requests_cache/backends/__init__.py
index 1296584..64da2c6 100644
--- a/requests_cache/backends/__init__.py
+++ b/requests_cache/backends/__init__.py
@@ -1,4 +1,6 @@
-"""Classes and functions for cache persistence"""
+"""Classes and functions for cache persistence. See :ref:`user_guide:cache backends` for general
+usage info.
+"""
 # flake8: noqa: F401
 from inspect import signature
 from logging import getLogger
diff --git a/requests_cache/backends/base.py b/requests_cache/backends/base.py
index fa03a8c..058b8fb 100644
--- a/requests_cache/backends/base.py
+++ b/requests_cache/backends/base.py
@@ -1,3 +1,9 @@
+"""Base classes for all cache backends.
+
+.. automodsumm:: requests_cache.backends.base
+   :classes-only:
+   :nosignatures:
+"""
 import pickle
 from abc import ABC
 from collections import UserDict
diff --git a/requests_cache/cache_control.py b/requests_cache/cache_control.py
index 52e8fa8..18ff919 100644
--- a/requests_cache/cache_control.py
+++ b/requests_cache/cache_control.py
@@ -1,4 +1,13 @@
-"""Internal utilities for determining cache expiration and other cache actions"""
+"""Internal utilities for determining cache expiration and other cache actions.
+
+.. automodsumm:: requests_cache.cache_control
+   :classes-only:
+   :nosignatures:
+
+.. automodsumm:: requests_cache.cache_control
+   :functions-only:
+   :nosignatures:
+"""
 from __future__ import annotations
 
 from datetime import datetime, timedelta, timezone
diff --git a/requests_cache/cache_keys.py b/requests_cache/cache_keys.py
index eb0f29e..78966c5 100644
--- a/requests_cache/cache_keys.py
+++ b/requests_cache/cache_keys.py
@@ -1,5 +1,9 @@
 """Internal utilities for generating cache keys based on request details + :py:class:`.BaseCache`
 settings
+
+.. automodsumm:: requests_cache.cache_keys
+   :functions-only:
+   :nosignatures:
 """
 from __future__ import annotations
 
diff --git a/requests_cache/patcher.py b/requests_cache/patcher.py
index 9b906a7..85f8908 100644
--- a/requests_cache/patcher.py
+++ b/requests_cache/patcher.py
@@ -1,7 +1,11 @@
 """Utilities for patching ``requests``.
 
-.. warning:: These functions are not thread-safe. Use :py:class:`.CachedSession` directly if you
-    want to use caching in a multi-threaded environment.
+.. warning:: These functions are not thread-safe. Use :py:class:`.CachedSession` if you want to use
+    caching in a multi-threaded environment.
+
+.. automodsumm:: requests_cache.patcher
+   :functions-only:
+   :nosignatures:
 """
 from contextlib import contextmanager
 from logging import getLogger
diff --git a/requests_cache/serializers/cattrs.py b/requests_cache/serializers/cattrs.py
index 9613092..69dd7d4 100644
--- a/requests_cache/serializers/cattrs.py
+++ b/requests_cache/serializers/cattrs.py
@@ -1,3 +1,16 @@
+"""
+Utilities to break down :py:class:`.CachedResponse` objects into python builtin types using
+`cattrs <https://cattrs.readthedocs.io>`_. This does the majority of the work needed for any
+serialization format.
+
+.. automodsumm:: requests_cache.serializers.cattrs
+   :classes-only:
+   :nosignatures:
+
+.. automodsumm:: requests_cache.serializers.cattrs
+   :functions-only:
+   :nosignatures:
+"""
 from datetime import datetime, timedelta
 from typing import Callable, Dict, ForwardRef, MutableMapping
 
@@ -11,11 +24,8 @@ from .pipeline import Stage
 
 
 class CattrStage(Stage):
-    """Base serializer class for :py:class:`.CachedResponse` that does pre/post-processing with
-    ``cattrs``. This does the majority of the work needed for any other serialization format,
-    breaking down objects into python builtin types.
-
-    This can be used as a stage within a :py:class:`.SerializerPipeline`.
+    """Base serializer class that does pre/post-processing with  ``cattrs``. This can be used either
+    on its own, or as a stage within a :py:class:`.SerializerPipeline`.
     """
 
     def __init__(self, factory: Callable[..., GenConverter] = None):
diff --git a/requests_cache/serializers/pipeline.py b/requests_cache/serializers/pipeline.py
index e16799f..fec7889 100644
--- a/requests_cache/serializers/pipeline.py
+++ b/requests_cache/serializers/pipeline.py
@@ -1,3 +1,8 @@
+"""
+.. automodsumm:: requests_cache.serializers.pipeline
+   :classes-only:
+   :nosignatures:
+"""
 from typing import Any, List, Union
 
 from ..models import CachedResponse
diff --git a/requests_cache/session.py b/requests_cache/session.py
index 798f072..1d2fbad 100644
--- a/requests_cache/session.py
+++ b/requests_cache/session.py
@@ -1,4 +1,18 @@
-"""Main classes to add caching features to ``requests.Session``"""
+"""Main classes to add caching features to ``requests.Session``
+
+.. autosummary::
+   :nosignatures:
+
+   CachedSession
+   CacheMixin
+
+.. Explicitly show inherited method docs on CachedSession instead of CachedMixin
+.. autoclass:: requests_cache.session.CachedSession
+    :show-inheritance:
+    :inherited-members:
+
+.. autoclass:: requests_cache.session.CacheMixin
+"""
 from contextlib import contextmanager
 from logging import getLogger
 from threading import RLock