Begun documenting faq and features. Fix #119 and #117.

3 files changed, 63 insertions, 0 deletions

diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..561df15
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,40 @@
+F.A.Q
+=====
+
+What parts of OAuth 1 & 2 is supported?
+    See :doc:`feature_matrix`.
+
+What is the difference between a client and a consumer?
+    None, they both refer to the third-party accessing protected resources
+    from an OAuth provider on behalf of a user. In order to do so they have
+    to obtain authorization from said user, which is what the `Auth` in `OAuth`
+    stands for.
+
+How do I use OAuthLib with Google, Twitter and other providers?
+    Most people will be using OAuthLib indirectly. Clients will want to look at
+    `requests-oauthlib`_.
+    
+How do I use OAuthlib as a provider with Django, Flask and other web frameworks?
+    Providers using Django should seek out `django-oauth-toolkit`_
+    and those using Flask `flask-oauthlib`_. For other frameworks,
+    please get in touch by opening a `GitHub issue`_, on `G+`_ or
+    on IRC #oauthlib irc.freenode.net.
+
+What is the difference between authentication and authorization?
+    See `difference`_.
+
+Very briefly, what is the biggest difference between OAuth 1 and 2?
+    OAuth 2 is much simpler since it requires the use of TLS whereas OAuth 1
+    had the requirement to work securely without TLS. To be secure without TLS
+    OAuth 1 required each request to be signed which can be cumbersome.
+
+Some argue OAuth 2 is worse than 1, is that true?
+    Correctly implemented, OAuth 2 is better in many ways than OAuth 1. Getting
+    it right is not trivial and a task OAuthLib aims to help make simple.
+
+.. _`requests-oauthlib`: https://github.com/requests/requests-oauthlib
+.. _`django-oauth-toolkit`: https://github.com/evonove/django-oauth-toolkit
+.. _`flask-oauthlib`: https://github.com/lepture/flask-oauthlib
+.. _`GitHub issue`: https://github.com/idan/oauthlib/issues/new
+.. _`G+`: https://plus.google.com/communities/101889017375384052571
+.. _`difference`: http://www.cyberciti.biz/faq/authentication-vs-authorization/
diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
new file mode 100644
index 0000000..d3adce6
--- /dev/null
+++ b/docs/feature_matrix.rst
@@ -0,0 +1,21 @@
+Supported features
+==================
+
+OAuth 1 is fully supported per the RFC for both clients and providers.
+Extensions and variations that are outside the spec are not supported.
+
+- HMAC-SHA1, RSA-SHA1 and plaintext signatures.
+- Signature placement in header, url or body.
+
+OAuth 2 client and provider support for
+
+- Authorization Code Grant
+- Implicit Grant
+- Client Credentials Grant
+- Resource Owner Password Credentials Grant
+- Refresh Tokens
+- Bearer Tokens
+- draft MAC tokens
+
+with support for SAML2 and JWT tokens, token revocation, dynamic client
+registration and much more to come.
diff --git a/docs/index.rst b/docs/index.rst
index e341ad3..70d3b73 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,8 @@ For news and discussions please check out our `G+ OAuthLib community`_.
    :maxdepth: 2
 
    contributing
+   faq
+   feature_matrix
 
 .. toctree::
    :maxdepth: 2