11 files changed, 135 insertions, 5 deletions
diff --git a/docs/_static/collapsible_container.css b/docs/_static/collapsible_container.css
new file mode 100644
index 0000000..65542e2
--- /dev/null
+++ b/docs/_static/collapsible_container.css
@@ -0,0 +1,26 @@
+/* Taken from: https://github.com/plone/training/blob/master/_static/custom.css */
+
+.toggle {
+    background: none repeat scroll 0 0 #e7f2fa;
+    padding: 12px;
+    line-height: 24px;
+    margin-bottom: 24px;
+}
+
+.toggle .admonition-title {
+    display: block;
+    clear: both;
+    cursor: pointer;
+}
+
+.toggle .admonition-title:after {
+    content: " ▶";
+}
+
+.toggle .admonition-title.open:after {
+    content: " ▼";
+}
+
+.toggle p:last-child {
+    margin-bottom: 0;
+}
diff --git a/docs/_templates/page.html b/docs/_templates/page.html
new file mode 100644
index 0000000..724739b
--- /dev/null
+++ b/docs/_templates/page.html
@@ -0,0 +1,15 @@
+{# Taken from: https://github.com/plone/training/blob/master/_templates/page.html #}
+{% extends "!page.html" %}
+
+{% block footer %}
+ <script type="text/javascript">
+    $(document).ready(function() {
+        $(".toggle > *").hide();
+        $(".toggle .admonition-title").show();
+        $(".toggle .admonition-title").click(function() {
+            $(this).parent().children().not(".admonition-title").toggle(400);
+            $(this).parent().children(".admonition-title").toggleClass("open");
+        })
+    });
+</script>
+{% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
index cd7df64..6d92cad 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -65,3 +65,8 @@ autosectionlabel_prefix_document = True
 # HTML theme settings
 pygments_style = 'sphinx'
 html_theme = 'sphinx_rtd_theme'
+
+
+def setup(app):
+    """Run some additional steps after the Sphinx builder is initialized"""
+    app.add_css_file('collapsible_container.css')
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..daf2ee4
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,73 @@
+Examples
+--------
+This section contains some complete examples that demonstrate the main features of requests-cache.
+
+These 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/log_requests.py
+    :start-line: 2
+    :end-line: 3
+
+.. admonition:: Example code
+    :class: toggle
+
+    .. literalinclude:: ../examples/basic_usage.py
+        :lines: 1,6-
+
+
+Basic usage (with patching)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. include:: ../examples/session_patch.py
+    :start-line: 3
+    :end-line: 4
+
+.. admonition:: Example code
+    :class: toggle
+
+    .. literalinclude:: ../examples/session_patch.py
+        :lines: 1,6-
+
+
+Cache expiration
+~~~~~~~~~~~~~~~~
+.. include:: ../examples/expiration.py
+    :start-line: 2
+    :end-line: 3
+
+.. admonition:: Example code
+    :class: toggle
+
+    .. literalinclude:: ../examples/expiration.py
+        :lines: 1,5-
+
+
+Logging requests
+~~~~~~~~~~~~~~~~
+.. include:: ../examples/log_requests.py
+    :start-line: 2
+    :end-line: 3
+
+.. admonition:: Example code
+    :class: toggle
+
+    .. literalinclude:: ../examples/log_requests.py
+        :lines: 1,5-
+
+
+Converting an old cache
+~~~~~~~~~~~~~~~~~~~~~~~
+.. include:: ../examples/convert_cache.py
+    :start-line: 2
+    :end-line: 4
+
+.. admonition:: Example code
+    :class: toggle
+
+    .. literalinclude:: ../examples/convert_cache.py
+        :lines: 1,6-
+
+
diff --git a/docs/index.rst b/docs/index.rst
index 24a6db6..bb39011 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,6 +15,7 @@ Contents
     user_guide
     advanced_usage
     security
+    examples
     api
     contributing
     contributors
diff --git a/docs/related_projects.rst b/docs/related_projects.rst
index 5ceb81b..deca9cd 100644
--- a/docs/related_projects.rst
+++ b/docs/related_projects.rst
@@ -15,3 +15,5 @@ You can also check out these other python cache projects:
   ``aiohttp`` web server
 * `aiocache <https://github.com/aio-libs/aiocache>`_: General-purpose (not HTTP-specific) async cache
   backends
+* `flask-caching <https://github.com/sh4nks/flask-caching>`_: A server-side HTTP cache for
+  applications using the Flask framework
diff --git a/examples/README.md b/examples/README.md
index 6645a4e..0102fd8 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,2 +1,3 @@
 # Requests-Cache Examples
-This folder contains some complete examples for using the main features of requests-cache.
+This folder contains some complete examples that demonstrate the main features of requests-cache.
+These are also viewable on [readthedocs](https://requests-cache.readthedocs.io/en/latest/examples.html).
diff --git a/examples/basic_usage.py b/examples/basic_usage.py
index 5234e43..21651dc 100755
--- a/examples/basic_usage.py
+++ b/examples/basic_usage.py
@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 # flake8: noqa: F841
-"""A Simple example using requests-cache with httpbin"""
+"""
+A simple example using requests-cache with httpbin
+"""
 import time
 
 from requests_cache import CachedSession
diff --git a/examples/convert_cache.py b/examples/convert_cache.py
index ce4f18f..a016bed 100755
--- a/examples/convert_cache.py
+++ b/examples/convert_cache.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python
-"""Example of converting data cached in older versions of requests-cache (<=0.5.2)
+"""
+Example of converting data cached in older versions of requests-cache (<=0.5.2)
 into the current format
 """
 from requests import Response
diff --git a/examples/expiration.py b/examples/expiration.py
index 4afa5fa..942b198 100755
--- a/examples/expiration.py
+++ b/examples/expiration.py
@@ -1,5 +1,7 @@
 #!/usr/bin/env python
-"""An example of setting expiration for individual requests"""
+"""
+An example of setting expiration for individual requests
+"""
 import time
 
 from requests_cache import CachedSession
diff --git a/examples/session_patch.py b/examples/session_patch.py
index f84e72e..4310687 100755
--- a/examples/session_patch.py
+++ b/examples/session_patch.py
@@ -1,6 +1,8 @@
 #!/usr/bin/env python
 # flake8: noqa: F841
-"""The same as `basic_usage.py`, but using global session patching"""
+"""
+The same as ``basic_usage.py``, but using global session patching
+"""
 import time
 
 import requests