Add Font Awesome 5 icons to main page headers

25 files changed, 47 insertions, 33 deletions

diff --git a/docs/conf.py b/docs/conf.py
index bcb4311..a19e0ad 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -38,6 +38,7 @@ extensions = [
     'sphinx_automodapi.smart_resolver',
     'sphinx_copybutton',
     'sphinx_inline_tabs',
+    'sphinx_panels',
     'sphinxcontrib.apidoc',
     'myst_parser',
 ]
@@ -94,7 +95,12 @@ apidoc_toc_file = False
 # 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 @@ html_theme_options = {
     '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
index 5f9c737..e190b7f 100644
--- 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
index 08e3bb3..7d0e4e5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -26,7 +26,7 @@ Documentation for the latest stable release can be found at [requests-cache.read
 :maxdepth: 2
 
 user_guide
-examples
 reference
+examples
 project_info
 ````
diff --git a/docs/project_info.md b/docs/project_info.md
index c296c1a..e87613c 100644
--- a/docs/project_info.md
+++ b/docs/project_info.md
@@ -1,4 +1,4 @@
-# Project Info
+# {fa}`info-circle` Project Info
 
 ```{toctree}
 :maxdepth: 2
diff --git a/docs/project_info/code_of_conduct.md b/docs/project_info/code_of_conduct.md
index 36beb23..a6d11be 100644
--- 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
index 01f6808..6a4e94d 100644
--- 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
index f0c9bb7..5c3aaa1 100644
--- 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
index ba5ca18..3bb2b72 100644
--- 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/related_projects.md b/docs/project_info/related_projects.md
index e9abcdc..cf581b6 100644
--- 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
index 563843c..f5a1b8a 100644
--- 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
index fcf24e4..c36c1e3 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -1,9 +1,9 @@
 (user-guide)=
-# User Guide
+# {fa}`book` User Guide
 This section covers the main features of requests-cache.
 
-## The Basics
 ```{toctree}
+:caption: The Basics
 :maxdepth: 2
 
 user_guide/installation
@@ -12,8 +12,8 @@ user_guide/files
 user_guide/troubleshooting
 ```
 
-## Features & Options
 ```{toctree}
+:caption: Features & Options
 :maxdepth: 2
 
 user_guide/backends
diff --git a/docs/user_guide/advanced_requests.md b/docs/user_guide/advanced_requests.md
index 71f2fdf..1a18939 100644
--- a/docs/user_guide/advanced_requests.md
+++ b/docs/user_guide/advanced_requests.md
@@ -1,4 +1,4 @@
-# Advanced Requests
+# {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.
diff --git a/docs/user_guide/backends.md b/docs/user_guide/backends.md
index d95c840..69084ba 100644
--- 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
index d52d610..3353471 100644
--- 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.
 
@@ -123,7 +123,7 @@ This has the advantage of only using request-mock's behavior for
 
 :::{admonition} Example code
 :class: toggle
-```{literalinclude} ../tests/compat/test_requests_mock_load_cache.py
+```{literalinclude} ../../tests/compat/test_requests_mock_load_cache.py
 :lines: 21-40
 ```
 :::
@@ -131,7 +131,7 @@ This has the advantage of only using request-mock's behavior for
 To turn that into a complete example:
 :::{admonition} Example code
 :class: toggle
-```{literalinclude} ../tests/compat/test_requests_mock_load_cache.py
+```{literalinclude} ../../tests/compat/test_requests_mock_load_cache.py
 ```
 :::
 
@@ -141,6 +141,6 @@ requests-mock examples above.
 
 :::{admonition} Example code
 :class: toggle
-```{literalinclude} ../tests/compat/test_responses_load_cache.py
+```{literalinclude} ../../tests/compat/test_responses_load_cache.py
 ```
 :::
diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index adb28ea..5892edd 100644
--- 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
index 5ef9040..36cb5fa 100644
--- 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.
diff --git a/docs/user_guide/filtering.md b/docs/user_guide/filtering.md
index 909a535..68e65f0 100644
--- 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
index e5d6562..78f1a02 100644
--- 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
index 8d1a795..bbdd9e9 100644
--- 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/inspection.md b/docs/user_guide/inspection.md
index bd26b68..c1db134 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -1,6 +1,6 @@
 <!-- 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
diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md
index 7435c57..98dd2a0 100644
--- 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
index fe0e145..1f9a338 100644
--- 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.
 
diff --git a/docs/user_guide/security.md b/docs/user_guide/security.md
index 45fbd0a..cad4d3f 100644
--- 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
index 46a94b7..9101731 100644
--- 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
index 34f8806..10c8c86 100644
--- a/docs/user_guide/troubleshooting.md
+++ b/docs/user_guide/troubleshooting.md
@@ -1,5 +1,5 @@
 (debug)=
-# Troubleshooting
+# {fa}`exclamation-circle` Troubleshooting
 Here are a few tips for avoiding and debugging some common problems.
 
 ## Potential Issues