Update README for 1.0 release

README.rst

@@ -2,18 +2,72 @@
 webfinger
 =========
 
+A simple Python client implementation of `WebFinger RFC 7033 <http://tools.ietf.org/html/rfc7033>`_.
+
+WebFinger is a discovery protocol that allows you to find information about people or things in a standardized way. See the `spec <http://tools.ietf.org/html/rfc7033>`_ or `webfinger.net <http://webfinger.net>`_ for more information.
+
+
 Usage
-=====
+-----
 
 Example::
 
-	from webfinger import finger
+    >>> from webfinger import finger
+    >>> wf = finger('acct:eric@konklone.com')
+    >>> wf.subject
+    acct:eric@konklone.com
+    >>> wf.avatar
+    https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
+    >>> wf.profile
+    https://konklone.com
+    >>> wf.properties.get('http://schema.org/name')
+    Eric Mill
 
-	wf = finger('user@host.com')
-	print wf.profile
-	print wf.hcard
 
-The following relation types are supported:
+WebFinger Response
+------------------
+
+The WebFinger response object provides handy properties for easy access and the raw JRD response. Read the `spec for specifics of the JRD response <http://tools.ietf.org/html/rfc7033#section-4.4>`_.
+
+
+----------
+Properties
+----------
+
+subject
+  The URI of the thing that the response JRD describes.
+
+aliases
+  A list of additional URIs that identify the subject.
+
+properties
+  A dict of URIs and values that provides information about the subject.
+
+links
+  A list of dicts that define external resources for the subject.
+
+jrd
+  A dict of the raw JRD response.
+
+
+-------
+Methods
+-------
+
+rel(relation, attr='href')
+  A convenience method that provides basic access to links. The *relation* parameter is a URI for the desired link. The *attr* parameter is the key of the returned value of the link that matches *relation*. Returns a string if *relation* and *attr* exist, otherwise *None*.
+
+Example::
+
+    >>> wf.rel('http://webfinger.net/rel/avatar')
+    https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
+
+
+-------------------
+Relation Properties
+-------------------
+
+The following common link relation types are supported as properties of the response object:
 
 * activity_streams: http://activitystrea.ms/spec/1.0
 * avatar: http://webfinger.net/rel/avatar
@@ -22,20 +76,32 @@ The following relation types are supported:
 * opensocial: http://ns.opensocial.org/2008/opensocial/activitystreams
 * portable_contacts: http://portablecontacts.net/spec/1.0
 * profile: http://webfinger.net/rel/profile-page
+* webfist: http://webfist.org/spec/rel
 * xfn: http://gmpg.org/xfn/11
 
-Other relation types can be accessed directly from the XRD document.::
+Example::
+
+    >>> wf.avatar
+    https://secure.gravatar.com/avatar/ac3399caecce27cb19d381f61124539e.jpg?s=400
+
+
+Unofficial Endpoints
+--------------------
+
+While Facebook and Twitter do not officially support WebFinger, the `webfinger-unofficial project <https://github.com/snarfed/webfinger-unofficial>`_ provides a proxy for basic subject information. By default, python-webfinger will attempt to use unoffical the endpoints for facebook.com and twitter.com resource domains. This behavior can be disabled by passing *True* to the *official* parameter::
+
+    >>> wf = finger('acct:konklone@twitter.com', official=True)
 
-	print wf.find_link('http://example.com/example/spec', attr='href')
 
 Dependencies
-============
+------------
+
+* `requests <https://pypi.python.org/pypi/requests>`_
 
-* `python-rd <http://github.com/jcarbaugh/python-rd>`_
 
 License
-=======
+-------
 
 python-webfinger is distributed under the `BSD license <http://creativecommons.org/licenses/BSD/>`_.
 
-See LICENSE for the full terms of the BSD license.
+See LICENSE for the full terms.