From 77dded143659302987c621b8c60ccd50b4679a79 Mon Sep 17 00:00:00 2001
From: Julian Berman <Julian@GrayVines.com>
Date: Tue, 25 Apr 2023 14:37:05 -0400
Subject: [PATCH] Minor simplification to the docs structure.

Fold retrieve documentation into the intro.
---
 docs/changes.rst            |  5 +++++
 docs/external-retrieval.rst | 29 -----------------------------
 docs/index.rst              |  3 +--
 docs/intro.rst              | 34 ++++++++++++++++++++++++++++++++++
 4 files changed, 40 insertions(+), 31 deletions(-)
 delete mode 100644 docs/external-retrieval.rst

diff --git a/docs/changes.rst b/docs/changes.rst
index de5d7c4..1eb038b 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -2,6 +2,11 @@
 Changelog
 =========
 
+v0.27.4
+-------
+
+* Minor simplification to the docs structure.
+
 v0.27.3
 -------
 
diff --git a/docs/external-retrieval.rst b/docs/external-retrieval.rst
deleted file mode 100644
index 8942e73..0000000
--- a/docs/external-retrieval.rst
+++ /dev/null
@@ -1,29 +0,0 @@
-==================
-External Retrieval
-==================
-
-`Registry` objects represent collections of in-memory resources (e.g. in the case of JSON Schema registries, they represent collections of in-memory JSON Schemas).
-
-Occasionally one wishes to dynamically fetch resources from some other location.
-We'll refer to resources not present in-memory as "external resources"
-
-The JSON Schema specifications generally discourage implementations from automatically retrieving network resources [#]_, but if you are in a situation where you wish to do so, or if you wish alternatively to load resources from a database, or from the filesystem, you can do so via the ``retrieve`` argument to `Registry` objects.
-
-Here's an example of how to automatically retrieve external references by downloading them from their URI via :httpx:`httpx </>`, shown by automatically retrieving one of the JSON Schema metaschemas from the network:
-
-.. code:: python
-
-    from referencing import Registry, Resource
-    import httpx
-
-
-    def retrieve_via_httpx(uri):
-        response = httpx.get(uri)
-        return Resource.from_contents(response.json())
-
-
-    registry = Registry(retrieve=retrieve_via_httpx)
-    resolver = registry.resolver()
-    print(resolver.lookup("https://json-schema.org/draft/2020-12/schema"))
-
-.. [#] Often for good security reasons. See :kw:`schema-references`.
diff --git a/docs/index.rst b/docs/index.rst
index 3dd09c4..ffa00d8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,8 +7,7 @@ In other words, a way for e.g. JSON Schema tooling to resolve the ``$ref`` keywo
     :hidden:
 
     intro
-    external-retrieval
     schema-packages
+    compatibility
     api
     changes
-    compatibility
diff --git a/docs/intro.rst b/docs/intro.rst
index 1bbdaad..6fe21ea 100644
--- a/docs/intro.rst
+++ b/docs/intro.rst
@@ -53,6 +53,7 @@ You could also confirm your resource is in the registry if you'd like, via `refe
 
    {'type': 'integer'}
 
+
 Populating Registries
 ---------------------
 
@@ -202,3 +203,36 @@ which now allows us to use the URI we associated with our third resource to retr
 If you have more than one resource to add, you can use `Registry.with_resources` (with an ``s``) to add many at once, or, if they meet the criteria to use ``@``, you can use ``[one, two, three] @ registry`` to add all three resources at once.
 
 You may also want to have a look at `Registry.with_contents` for a further method to add resources to a registry without constructing a `Resource` object yourself.
+
+
+Dynamically Retrieving Resources
+--------------------------------
+
+Sometimes one wishes to dynamically retrieve or construct `Resource`\ s which *don't* already live in-memory within a `Registry`.
+This might be resources retrieved dynamically from a database, from files somewhere on disk, from some arbitrary place over the internet, or from the like.
+We'll refer to such resources not present in-memory as *external resources*.
+
+The ``retrieve`` argument to ``Registry`` objects can be used to configure a callable which will be used anytime a requested URI is *not* present in the registry, thereby allowing you to retrieve it from whichever location it lives in.
+Here's an example of automatically retrieving external references by downloading them via :httpx:`httpx </>`, illustrated by then automatically retrieving one of the JSON Schema metaschemas from the network:
+
+.. code:: python
+
+    from referencing import Registry, Resource
+    import httpx
+
+
+    def retrieve_via_httpx(uri):
+        response = httpx.get(uri)
+        return Resource.from_contents(response.json())
+
+
+    registry = Registry(retrieve=retrieve_via_httpx)
+    resolver = registry.resolver()
+    print(resolver.lookup("https://json-schema.org/draft/2020-12/schema"))
+
+.. note::
+
+    In the case of JSON Schema, the specifications generally discourage implementations from automatically retrieving these sorts of external resources over the network due to potential security implications.
+    See :kw:`schema-references` in particular.
+
+    `referencing` will of course therefore not do any such thing automatically, and this section generally assumes that you have personally considered the security implications for your own use case.