Merge 95dd646 into c589282

requests-cache · Aug 27, 2021 · 2492f2b · 2492f2b
2 parents c589282 + 95dd646
commit 2492f2b
Show file tree

Hide file tree

Showing 29 changed files with 195 additions and 94 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -38,6 +38,7 @@
     'sphinx_automodapi.smart_resolver',
     'sphinx_copybutton',
     'sphinx_inline_tabs',
+    'sphinx_panels',
     'sphinxcontrib.apidoc',
     'myst_parser',
 ]
@@ -94,7 +95,12 @@
 # HTML general settings
 html_favicon = join('_static', 'favicon.ico')
 html_js_files = ['collapsible_container.js']
-html_css_files = ['collapsible_container.css', 'table.css']
+html_css_files = [
+    'collapsible_container.css',
+    'table.css',
+    'https://use.fontawesome.com/releases/v5.15.3/css/all.css',
+    'https://use.fontawesome.com/releases/v5.15.3/css/v4-shims.css',
+]
 html_show_sphinx = False
 pygments_style = 'friendly'
 pygments_dark_style = 'material'
@@ -106,11 +112,11 @@
     'dark_logo': 'requests-cache-logo-white.png',
     'sidebar_hide_name': True,
     'light_css_variables': {
-        'color-brand-primary': '#2962ff',
+        'color-brand-primary': '#0288d1',
         'color-brand-content': '#2a5adf',
     },
     'dark_css_variables': {
-        'color-brand-primary': '#2b8cee',
+        'color-brand-primary': '#5eb8ff',
         'color-brand-content': '#368ce2',
     },
 }

diff --git a/docs/examples.md b/docs/examples.md
@@ -1,5 +1,5 @@
 (examples)=
-# Examples
+# {fa}`laptop-code` Examples
 This section contains some complete examples that demonstrate the main features of requests-cache.
 
 ## Articles

diff --git 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
-examples
+user_guide
 reference
-project_info/index
+examples
+project_info
 ````
diff --git a/docs/project_info.md b/docs/project_info.md
@@ -0,0 +1,11 @@
+# {fa}`info-circle` 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/code_of_conduct.md b/docs/project_info/code_of_conduct.md
@@ -1,2 +1,4 @@
+# {fa}`handshake` Code of Conduct
 ```{include} ../../.github/CODE_OF_CONDUCT.md
+:start-line: 1
 ```
diff --git a/docs/project_info/contributing.md b/docs/project_info/contributing.md
@@ -1,3 +1,5 @@
 (contributing)=
+# {fa}`lightbulb` Contributing
 ```{include} ../../CONTRIBUTING.md
+:start-line: 1
 ```
diff --git a/docs/project_info/contributors.md b/docs/project_info/contributors.md
@@ -1,2 +1,4 @@
+# {fa}`users` Contributors
 ```{include} ../../CONTRIBUTORS.md
+:start-line: 1
 ```
diff --git a/docs/project_info/history.md b/docs/project_info/history.md
@@ -1,3 +1,5 @@
 (changelog)=
+# {fa}`history` History
 ```{include} ../../HISTORY.md
+:start-line: 1
 ```
diff --git a/docs/project_info/index.md b/docs/project_info/index.md
diff --git a/docs/project_info/related_projects.md b/docs/project_info/related_projects.md
@@ -1,5 +1,5 @@
 (related-projects)=
-# Related Projects
+# {fa}`external-link` Related Projects
 If requests-cache isn't quite what you need, you can help make it better! See the
 {ref}`Contributing Guide <contributing>` for details.
 

diff --git a/docs/reference.md b/docs/reference.md
@@ -1,7 +1,6 @@
 % Note: The module sources referenced here are auto-generated with apidoc
 (reference)=
-
-# API Reference
+# {fa}`list` API Reference
 This section covers all the public interfaces of requests-cache.
 
 :::{tip}

diff --git a/docs/user_guide.md b/docs/user_guide.md
@@ -0,0 +1,29 @@
+(user-guide)=
+# {fa}`book` User Guide
+This section covers the main features of requests-cache.
+
+```{toctree}
+:caption: The Basics
+:maxdepth: 2
+
+user_guide/installation
+user_guide/general
+user_guide/files
+user_guide/troubleshooting
+```
+
+```{toctree}
+:caption: Features & Options
+: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
@@ -1,8 +1,10 @@
-<!-- TODO: Better title for this section -->
-# Usage with other requests features
+# {fa}`info-circle` 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/backends.md b/docs/user_guide/backends.md
@@ -1,5 +1,5 @@
 (backends)=
-# Backends
+# {fa}`database` Backends
 ![](../_static/sqlite_32px.png)
 ![](../_static/redis_32px.png)
 ![](../_static/mongodb_32px.png)
@@ -8,14 +8,15 @@
 
 Several cache backends are included. The default is SQLite, since it's generally the simplest to
 use, and requires no extra dependencies or configuration.
+
+See {py:mod}`.requests_cache.backends` for usage details for specific backends.
+
 ```{note}
 In the rare case that SQLite is not available
 (for example, [on Heroku](https://devcenter.heroku.com/articles/sqlite3)), a non-persistent
 in-memory cache is used by default.
 ```
 
-See {py:mod}`.requests_cache.backends` for usage details for specific backends.
-
 ## Backend Dependencies
 Most of the other backends require some extra dependencies, listed below.
 

diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
@@ -1,6 +1,6 @@
 <!-- TODO: Fix relative links -->
 (compatibility)=
-# Usage with other requests-based libraries
+# {fa}`plus-square` Usage with other requests-based libraries
 This library works by patching and/or extending {py:class}`requests.Session`. Many other libraries
 out there do the same thing, making it potentially difficult to combine them.
 

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
@@ -1,5 +1,5 @@
 (expiration)=
-# Expiration
+# {fa}`clock` Expiration
 By default, cached responses will be stored indefinitely. There are a number of options for
 specifying how long to store responses, either with a single expiration value, glob patterns,
 or {ref}`cache headers <headers>`.

diff --git a/docs/user_guide/files.md b/docs/user_guide/files.md
@@ -1,8 +1,8 @@
 (files)=
-# Cache Files
+# {fa}`folder-open` Cache Files
 ```{note}
-This section only applies to the {py:mod}`~requests_cache.backends.sqlite` and
-{py:mod}`~requests_cache.backends.filesystem` backends.
+This section only applies to the {py:mod}`SQLite <requests_cache.backends.sqlite>` and
+{py:mod}`Filesystem <requests_cache.backends.filesystem>` backends.
 ```
 For file-based backends, the cache name will be used as a path to the cache file(s). You can use
 a relative path, absolute path, or use some additional options for system-specific default paths.
@@ -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/filtering.md b/docs/user_guide/filtering.md
@@ -1,5 +1,5 @@
 (filtering)=
-# Cache Filtering
+# {fa}`filter` Cache Filtering
 In many cases you will want to choose what you want to cache instead of just caching everything. By
 default, all **read-only** (`GET` and `HEAD`) **requests with a 200 response code** are cached. A
 few options are available to modify this behavior.

diff --git a/docs/user_guide/general.md b/docs/user_guide/general.md
@@ -1,5 +1,5 @@
 (general)=
-# General Usage
+# {fa}`play-circle` General Usage
 There are two main ways of using requests-cache:
 - **Sessions:** (recommended) Use {py:class}`.CachedSession` to send your requests
 - **Patching:** Globally patch `requests` using {py:func}`.install_cache()`

diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
@@ -1,5 +1,5 @@
 (headers)=
-# Cache Headers
+# {fa}`file-code` Cache Headers
 Most common request and response headers related to caching are supported, including
 [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
 and [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag).

diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
@@ -1,14 +1,17 @@
 <!-- TODO: This could use some more details and examples -->
 (inspection)=
-# Cache Inspection
+# {fa}`search` Cache Inspection
 Here are some ways to get additional information out of the cache session, backend, and responses:
 
 ## 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/installation.md b/docs/user_guide/installation.md
@@ -1,4 +1,4 @@
-# Installation
+# {fa}`download` Installation
 Installation instructions:
 
 :::{tab} Pip

diff --git a/docs/user_guide/matching.md b/docs/user_guide/matching.md
@@ -1,5 +1,5 @@
 (matching)=
-# Request Matching
+# {fa}`equals` Request Matching
 Requests are matched according to the request URL, parameters and body. All of these values are
 normalized to account for any variations that do not modify response content.
 
@@ -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/security.md b/docs/user_guide/security.md
@@ -1,5 +1,5 @@
 (security)=
-# Security
+# {fa}`lock` Security
 
 ## Pickle Vulnerabilities
 :::{warning}

diff --git a/docs/user_guide/serializers.md b/docs/user_guide/serializers.md
@@ -1,5 +1,5 @@
 (serializers)=
-# Serializers
+# {fa}`barcode` Serializers
 ![](../_static/file-pickle_32px.png)
 ![](../_static/file-json_32px.png)
 ![](../_static/file-yaml_32px.png)

diff --git a/docs/user_guide/troubleshooting.md b/docs/user_guide/troubleshooting.md
@@ -1,10 +1,60 @@
-<!-- TODO: Logging, tracebacks, submitting issues, etc. -->
-# Troubleshooting
+(debug)=
+# {fa}`exclamation-circle` 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