Add more details on troubleshooting & debugging

10 files changed, 113 insertions, 48 deletions

diff --git a/docs/index.md b/docs/index.md
index df9f4bd..08e3bb3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,8 +25,8 @@ Documentation for the latest stable release can be found at [requests-cache.read
 ```{toctree}
 :maxdepth: 2
 
-user_guide/index
+user_guide
 examples
 reference
-project_info/index
+project_info
 ````
diff --git a/docs/project_info.md b/docs/project_info.md
new file mode 100644
index 0000000..c296c1a
--- /dev/null
+++ b/docs/project_info.md
@@ -0,0 +1,11 @@
+# Project Info
+
+```{toctree}
+:maxdepth: 2
+
+project_info/contributing
+project_info/contributors
+project_info/code_of_conduct
+project_info/related_projects
+project_info/history
+````
diff --git a/docs/project_info/index.md b/docs/project_info/index.md
deleted file mode 100644
index c808ab6..0000000
--- a/docs/project_info/index.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Project Info
-
-```{toctree}
-:maxdepth: 2
-
-contributing
-contributors
-code_of_conduct
-related_projects
-history
-````
diff --git a/docs/user_guide.md b/docs/user_guide.md
new file mode 100644
index 0000000..fcf24e4
--- /dev/null
+++ b/docs/user_guide.md
@@ -0,0 +1,29 @@
+(user-guide)=
+# User Guide
+This section covers the main features of requests-cache.
+
+## The Basics
+```{toctree}
+:maxdepth: 2
+
+user_guide/installation
+user_guide/general
+user_guide/files
+user_guide/troubleshooting
+```
+
+## Features & Options
+```{toctree}
+:maxdepth: 2
+
+user_guide/backends
+user_guide/filtering
+user_guide/headers
+user_guide/inspection
+user_guide/expiration
+user_guide/matching
+user_guide/security
+user_guide/serializers
+user_guide/advanced_requests
+user_guide/compatibility
+```
diff --git a/docs/user_guide/advanced_requests.md b/docs/user_guide/advanced_requests.md
index 7115a7f..71f2fdf 100644
--- a/docs/user_guide/advanced_requests.md
+++ b/docs/user_guide/advanced_requests.md
@@ -1,8 +1,10 @@
-<!-- TODO: Better title for this section -->
-# Usage with other requests features
+# Advanced Requests
+Following are some tips on using requests-cache with some of the more
+[advanced features](https://docs.python-requests.org/en/latest/user/advanced/) of the requests
+library.
 
-## Request Hooks
-Requests has an [Event Hook](https://requests.readthedocs.io/en/master/user/advanced/#event-hooks)
+## Event Hooks
+Requests has an [event hook](https://requests.readthedocs.io/en/master/user/advanced/#event-hooks)
 system that can be used to add custom behavior into different parts of the request process.
 It can be used, for example, for request throttling:
 
diff --git a/docs/user_guide/files.md b/docs/user_guide/files.md
index de1325d..5ef9040 100644
--- a/docs/user_guide/files.md
+++ b/docs/user_guide/files.md
@@ -35,8 +35,7 @@ You can also give an absolute path, including user paths (with `~`).
 
 ## System Paths
 If you don't know exactly where you want to put your cache files, your system's **temp directory**
-or **cache directory** is a good choice. Some options are available as shortcuts to use whatever the
-default locations are for your operating system.
+or **cache directory** is a good choice. Some options are available as shortcuts for these locations.
 
 Use the default temp directory with the `use_temp` option:
 :::{tab} Linux
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
deleted file mode 100644
index d28a108..0000000
--- a/docs/user_guide/index.md
+++ /dev/null
@@ -1,21 +0,0 @@
-(user-guide)=
-# User Guide
-This section covers the main features of requests-cache.
-
-```{toctree}
-:maxdepth: 2
-
-installation
-general
-backends
-files
-filtering
-headers
-inspection
-expiration
-matching
-security
-serializers
-troubleshooting
-compatibility
-````
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
index 1ba560d..bd26b68 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -6,9 +6,12 @@ Here are some ways to get additional information out of the cache session, backe
 ## Response Details
 The following attributes are available on responses:
 - `from_cache`: indicates if the response came from the cache
+- `cache_key`: The unique identifier used to match the request to the response (see {ref}`matching`
+  for details)
 - `created_at`: {py:class}`~datetime.datetime` of when the cached response was created or last updated
-- `expires`: {py:class}`~datetime.datetime` after which the cached response will expire
-- `is_expired`: indicates if the cached response is expired (if an old response was returned due to a request error)
+- `expires`: {py:class}`~datetime.datetime` after which the cached response will expire (see
+  {ref}`expiration` for details)
+- `is_expired`: indicates if the cached response is expired (if, for example, an old response was returned due to a request error)
 
 Examples:
 :::{admonition} Example code
diff --git a/docs/user_guide/matching.md b/docs/user_guide/matching.md
index 333d868..fe0e145 100644
--- a/docs/user_guide/matching.md
+++ b/docs/user_guide/matching.md
@@ -56,6 +56,7 @@ As well as headers, if `include_get_headers` is also used:
 Since `ignored_parameters` is most often used for sensitive info like credentials, these values will also be removed from the cached request parameters, body, and headers.
 ```
 
+(custom-matching)=
 ## Custom Request Matching
 If you need more advanced behavior, you can implement your own custom request matching.
 
diff --git a/docs/user_guide/troubleshooting.md b/docs/user_guide/troubleshooting.md
index e61bf84..34f8806 100644
--- a/docs/user_guide/troubleshooting.md
+++ b/docs/user_guide/troubleshooting.md
@@ -1,10 +1,62 @@
-<!-- TODO: Logging, tracebacks, submitting issues, etc. -->
+(debug)=
 # Troubleshooting
+Here are a few tips for avoiding and debugging some common problems.
 
 ## Potential Issues
-- See {ref}`monkeypatch-issues` for issues specific to {py:func}`.install_cache`
-- New releases of `requests`, `urllib3` or `requests-cache` itself may change response data and be
-  be incompatible with previously cached data (see issues
+* **Patching:** See {ref}`monkeypatch-issues` for notes specific to {py:func}`.install_cache`
+* **Imports:** It's recommended to import everything from the top-level `requests_cache` package.
+  Other internal modules and utilities may change with future releases.
+* **Library updates:** New releases of `requests`, `urllib3` or `requests-cache` itself can
+  potentially change response data, and be incompatible with previously cached responses. See issues
   [#56](https://github.com/reclosedev/requests-cache/issues/56) and
-  [#102](https://github.com/reclosedev/requests-cache/issues/102)).
-  In these cases, the cached data will simply be invalidated and a new response will be fetched.
+  [#102](https://github.com/reclosedev/requests-cache/issues/102).
+* **Cache settings:** Some issues may be caused by changing settings for an existing cache. For
+  example, if you are using {ref}`custom-serializers`, {ref}`custom-matching`, or other advanced
+  features, you may get unexpected behavior if you change those settings and reuse previously cached
+  data. In these cases, the easiest way to resolve the issue is to clear the cache with
+  ({py:meth}`CachedSession.cache.clear() <.BaseCache.clear>`).
+
+```{note}
+A cached response that can't be reused will simply be deleted and fetched again. If you get a
+traceback just by reading from the cache, this is **not** intended behavior, so please create a bug
+report!
+```
+
+## Logging
+Debug logging can be enabled with the standard python `logging` module, for example with
+{py:func}`logging.basicConfig`:
+```python
+import logging
+
+logging.basicConfig(level='DEBUG')
+```
+
+For prettier, more readable logs, try the [rich](https://github.com/willmcgugan/rich) library's
+[logging handler](https://rich.readthedocs.io/en/stable/logging.html):
+```python
+import logging
+from rich.logging import RichHandler
+
+logging.basicConfig(
+    level='DEBUG', format="%(message)s", datefmt="[%X]", handlers=[RichHandler()]
+)
+```
+
+If you have other libraries installed with verbose debug logging, you can configure only the loggers
+you want with `logger.setLevel()`:
+```python
+import logging
+
+logging.basicConfig(level='WARNING')
+logging.getLogger('requests_cache').setLevel('DEBUG')
+```
+
+## Bug Reports
+If you believe you've found a bug, or if you're just having trouble getting requests-cache to work
+the way you want, please
+[create an issue](https://github.com/reclosedev/requests-cache/issues/new/choose) for it on GitHub.
+
+Details that will help your issue get resolved:
+* A complete example to reproduce the issue
+* Tracebacks and logging output
+* Any other details about what you want to do and how you want it to work