6 files changed, 36 insertions, 49 deletions
diff --git a/docs/examples.md b/docs/examples.md
index b6866bc..d8477dc 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -16,27 +16,27 @@ The following scripts can also be found in the
 [examples/](https://github.com/reclosedev/requests-cache/tree/master/examples) folder on GitHub.
 
 ### Basic usage (with sessions)
-```{include} ../examples/basic_usage.py
+```{include} ../examples/basic_sessions.py
 :start-line: 3
 :end-line: 4
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: basic_sessions.py
 :class: toggle
-```{literalinclude} ../examples/basic_usage.py
+```{literalinclude} ../examples/basic_sessions.py
 :lines: 1,6-
 ```
 :::
 
 ### Basic usage (with patching)
-```{include} ../examples/session_patch.py
+```{include} ../examples/basic_patching.py
 :start-line: 3
 :end-line: 4
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: basic_patching.py
 :class: toggle
-```{literalinclude} ../examples/session_patch.py
+```{literalinclude} ../examples/basic_patching.py
 :lines: 1,6-
 ```
 :::
@@ -47,7 +47,7 @@ The following scripts can also be found in the
 :end-line: 3
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: expiration.py
 :class: toggle
 ```{literalinclude} ../examples/expiration.py
 :lines: 1,5-
@@ -60,7 +60,7 @@ The following scripts can also be found in the
 :end-line: 4
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: /url_patterns.py
 :class: toggle
 ```{literalinclude} ../examples/url_patterns.py
 :lines: 1,6-
@@ -73,7 +73,7 @@ The following scripts can also be found in the
 :end-line: 4
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: threads.py
 :class: toggle
 ```{literalinclude} ../examples/threads.py
 :lines: 1,6-
@@ -86,7 +86,7 @@ The following scripts can also be found in the
 :end-line: 3
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: log_requests.py
 :class: toggle
 ```{literalinclude} ../examples/log_requests.py
 :lines: 1,5-
@@ -99,7 +99,7 @@ The following scripts can also be found in the
 :end-line: 8
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: benchmark.py
 :class: toggle
 ```{literalinclude} ../examples/benchmark.py
 :lines: 1,10-
@@ -112,7 +112,7 @@ The following scripts can also be found in the
 :end-line: 4
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: convert_cache.py
 :class: toggle
 ```{literalinclude} ../examples/convert_cache.py
 :lines: 1,6-
@@ -126,7 +126,7 @@ The following scripts can also be found in the
 :end-line: 15
 ```
 
-:::{admonition} Example code
+:::{admonition} Example: custom_request_matcher.py
 :class: toggle
 ```{literalinclude} ../examples/custom_request_matcher.py
 :lines: 1,17-
diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
index 3353471..354f572 100644
--- a/docs/user_guide/compatibility.md
+++ b/docs/user_guide/compatibility.md
@@ -10,39 +10,33 @@ multiple Session-modifying libraries:
 >>> from requests import Session
 >>> from requests_cache import CacheMixin
 >>> from some_other_lib import SomeOtherMixin
->>>
+
 >>> class CustomSession(CacheMixin, SomeOtherMixin, Session):
 ...     """Session class with features from both some_other_lib and requests-cache"""
 ```
 
 ## Requests-HTML
 [requests-html](https://github.com/psf/requests-html) is one library that works with this method:
-:::{admonition} Example code
-:class: toggle
 ```python
 >>> import requests
 >>> from requests_cache import CacheMixin, install_cache
 >>> from requests_html import HTMLSession
->>>
+
 >>> class CachedHTMLSession(CacheMixin, HTMLSession):
 ...     """Session with features from both CachedSession and HTMLSession"""
->>>
+
 >>> session = CachedHTMLSession()
 >>> response = session.get('https://github.com/')
 >>> print(response.from_cache, response.html.links)
 ```
-:::
 
 
 Or if you are using {py:func}`.install_cache`, you can use the `session_factory` argument:
-:::{admonition} Example code
-:class: toggle
 ```python
 >>> install_cache(session_factory=CachedHTMLSession)
 >>> response = requests.get('https://github.com/')
 >>> print(response.from_cache, response.html.links)
 ```
-:::
 
 The same approach can be used with other libraries that subclass {py:class}`requests.Session`.
 
@@ -60,16 +54,13 @@ See [issue #135](https://github.com/reclosedev/requests-cache/issues/135) for mo
 ## Internet Archive
 Usage with [internetarchive](https://github.com/jjjake/internetarchive) is the same as other libraries
 that subclass `requests.Session`:
-:::{admonition} Example code
-:class: toggle
 ```python
 >>> from requests_cache import CacheMixin
 >>> from internetarchive.session import ArchiveSession
->>>
+
 >>> class CachedArchiveSession(CacheMixin, ArchiveSession):
 ...     """Session with features from both CachedSession and ArchiveSession"""
 ```
-:::
 
 ## Requests-mock
 [requests-mock](https://github.com/jamielennox/requests-mock) has multiple methods for mocking
@@ -82,35 +73,33 @@ your tests, the easiest thing to do is to disable requests-cache.
 
 For example, if you are using {py:func}`.install_cache` in your application and the
 requests-mock [pytest fixture](https://requests-mock.readthedocs.io/en/latest/pytest.html) in your
-tests, you could wrap it in another fixture that uses {py:func}`.uninstall_cache` or {py:func}`.disabled`:
-:::{admonition} Example code
+tests, you could wrap it in another fixture that uses {py:func}`.uninstall_cache` or
+{py:func}`.disabled`:
+:::{admonition} Example: test_requests_mock_disable_cache.py
 :class: toggle
 ```{literalinclude} ../../tests/compat/test_requests_mock_disable_cache.py
 ```
 :::
 
+
 Or if you use a `CachedSession` object, you could replace it with a regular `Session`, for example:
-:::{admonition} Example code
-:class: toggle
 ```python
-import unittest
-import pytest
-import requests
-
+>>> import unittest
+>>> import pytest
+>>> import requests
 
-@pytest.fixure(scope='function', autouse=True)
-def disable_requests_cache():
-    """Replace CachedSession with a regular Session for all test functions"""
-    with unittest.mock.patch('requests_cache.CachedSession', requests.Session):
-        yield
+>>> @pytest.fixure(scope='function', autouse=True)
+>>> def disable_requests_cache():
+...     """Replace CachedSession with a regular Session for all test functions"""
+...     with unittest.mock.patch('requests_cache.CachedSession', requests.Session):
+...         yield
 ```
-:::
 
 ### Combining requests-cache with requests-mock
 If you want both caching and mocking features at the same time, you can attach requests-mock's
 [adapter](https://requests-mock.readthedocs.io/en/latest/adapter.html) to a `CachedSession`:
 
-:::{admonition} Example code
+:::{admonition} Example: test_requests_mock_combine_cache.py
 :class: toggle
 ```{literalinclude} ../../tests/compat/test_requests_mock_combine_cache.py
 ```
@@ -121,15 +110,12 @@ Another approach is to use cached data to dynamically define mock requests + res
 This has the advantage of only using request-mock's behavior for
 [request matching](https://requests-mock.readthedocs.io/en/latest/matching.html).
 
-:::{admonition} Example code
-:class: toggle
 ```{literalinclude} ../../tests/compat/test_requests_mock_load_cache.py
 :lines: 21-40
 ```
-:::
 
 To turn that into a complete example:
-:::{admonition} Example code
+:::{admonition} Example: test_requests_mock_load_cache.py
 :class: toggle
 ```{literalinclude} ../../tests/compat/test_requests_mock_load_cache.py
 ```
@@ -139,7 +125,7 @@ To turn that into a complete example:
 Usage with the [responses](https://github.com/getsentry/responses) library is similar to the
 requests-mock examples above.
 
-:::{admonition} Example code
+:::{admonition} Example: test_responses_load_cache.py
 :class: toggle
 ```{literalinclude} ../../tests/compat/test_responses_load_cache.py
 ```
diff --git a/docs/user_guide/general.md b/docs/user_guide/general.md
index 78f1a02..2932a25 100644
--- a/docs/user_guide/general.md
+++ b/docs/user_guide/general.md
@@ -34,6 +34,7 @@ clear out everything at once with {py:meth}`.BaseCache.clear`:
 >>> session.cache.clear()
 ```
 
+(patching)=
 ## Patching
 In some situations, it may not be possible or convenient to manage your own session object. In those
 cases, you can use {py:func}`.install_cache` to add caching to all `requests` functions:
diff --git a/examples/session_patch.py b/examples/basic_patching.py
index 204320d..def0ead 100755
--- a/examples/session_patch.py
+++ b/examples/basic_patching.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # flake8: noqa: F841
 """
-The same as ``basic_usage.py``, but using global session patching
+The same as `basic_sessions.py`, but using {ref}`patching`
 """
 import time
 
diff --git a/examples/basic_usage.py b/examples/basic_sessions.py
index 3f0d82d..42a6dd2 100755
--- a/examples/basic_usage.py
+++ b/examples/basic_sessions.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # flake8: noqa: F841
 """
-A simple example using requests-cache with httpbin
+A simple example using requests-cache with [httpbin](https://httpbin.org)
 """
 import time
 
diff --git a/examples/generate_test_db.py b/examples/generate_test_db.py
index c58fb2a..7f3dd6b 100755
--- a/examples/generate_test_db.py
+++ b/examples/generate_test_db.py
@@ -47,7 +47,7 @@ def populate_cache(progress, task):
 
     # Cache a variety of different response formats, which may result in different behavior
     urls = [
-        ('GET', 'https://httpbin.org/{endpoint}')
+        ('GET', f'https://httpbin.org/{endpoint}')
         for endpoint in HTTPBIN_FORMATS + HTTPBIN_EXTRA_ENDPOINTS
     ]
     urls += [(method, 'https://httpbin.org/{method.lower()}') for method in HTTPBIN_METHODS]