Update docs

docs/index.rst

@@ -44,9 +44,9 @@ The primary interface to use :class:`JsonRef` objects is with the class method
 all JSON references contained replaced by :class:`JsonRef` objects. There are
 several other options you can pass, seen below.
 
-.. autoclass:: JsonRef(refobj, base_uri=None, loader=None, loader_kwargs=(), jsonschema=False, load_on_repr=True)
+.. autoclass:: JsonRef(refobj, base_uri=None, loader=None, jsonschema=False, load_on_repr=True)
 
-    .. automethod:: replace_refs(obj, base_uri=None, loader=None, loader_kwargs=(), jsonschema=False, load_on_repr=True)
+    .. automethod:: replace_refs(obj, base_uri=None, loader=None, jsonschema=False, load_on_repr=True)
 
     :class:`JsonRef` instances proxy almost all operators and attributes to the
     referent data, which will be loaded when first accessed. The following
@@ -63,6 +63,21 @@ several other options you can pass, seen below.
         will not cause the referent data to be loaded.
 
 
+Loading a document at a given URI
+=================================
+
+In order to actually get and parse the JSON at a given URI, :class:`JsonRef`
+objects pass the URI to a callable, set with the keyword argument ``loader``.
+This callable must take the URI as an argument, and return the parsed JSON
+referred to by that URI.
+
+The :class:`JsonLoader` class is provided to fill this role, and a default
+instance of it will be used for all refs unless a custom one is specified.
+
+.. autoclass:: JsonLoader
+    :members: __call__
+
+
 :mod:`json` module drop in replacement functions
 ================================================
 
@@ -74,13 +89,17 @@ load
 
 :func:`load` and :func:`loads` work just like their
 :mod:`json` counterparts, except for references will already be replaced in the
-return values. If you need to pass in custom parameters to :class:`JsonRef`,
-keyword arguments can be provided by the `ref_kwargs` argument.
+return values.
 
 .. autofunction:: load
 
 .. autofunction:: loads
 
+There is also a convenience function provided to load and process references on
+a document at a given uri using the specified ``loader``
+
+.. autofunction:: load_uri
+
 dump
 ----
 

jsonref.py

@@ -248,17 +248,17 @@ def __repr__(self):
 class JsonLoader(object):
     """
     Provides a callable which takes a URI, and returns the loaded JSON referred
-    to by that URI.
+    to by that URI. Uses :mod:`requests` if available for HTTP URIs, and falls
+    back to :mod:`urllib`. By default it keeps a cache of previously loaded
+    documents.
+
+    :param store: A pre-populated dictionary matching URIs to loaded JSON
+        documents
+    :param cache_results: If this is set to false, the internal cache of
+        loaded JSON documents is not used
 
     """
     def __init__(self, store=(), cache_results=True):
-        """
-        :param store: A pre-populated dictionary matching URIs to loaded JSON
-            documents
-        :param cache_results: If this is set to false, the internal cache of
-            loaded JSON documents is not used
-
-        """
         self.store = _URIDict(store)
         self.cache_results = cache_results
 
@@ -267,7 +267,7 @@ def __call__(self, uri, **kwargs):
         Return the loaded JSON referred to by `uri`
 
         :param uri: The URI of the JSON document to load
-        :param **kwargs: Keyword arguments passed to :func:`json.loads`
+        :param kwargs: Keyword arguments passed to :func:`json.loads`
 
         """
         if uri in self.store:
@@ -308,7 +308,7 @@ def load(
     proxied to their referent data.
 
     :param fp: File-like object containing JSON document
-    :param **kwargs: This function takes any of the keyword arguments from
+    :param kwargs: This function takes any of the keyword arguments from
         :meth:`JsonRef.replace_refs`. Any other keyword arguments will be passed to
         :func:`json.load`
 
@@ -335,7 +335,7 @@ def loads(
     proxied to their referent data.
 
     :param s: String containing JSON document
-    :param **kwargs: This function takes any of the keyword arguments from
+    :param kwargs: This function takes any of the keyword arguments from
         :meth:`JsonRef.replace_refs`. Any other keyword arguments will be passed to
         :func:`json.loads`
 
@@ -361,7 +361,7 @@ def load_uri(
     data.
 
     :param uri: URI to fetch the JSON from
-    :param **kwargs: This function takes any of the keyword arguments from
+    :param kwargs: This function takes any of the keyword arguments from
         :meth:`JsonRef.replace_refs`
 
     """