Merge branch 'master' into master

4 files changed, 57 insertions, 5 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index cbdb519..771262d 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -238,6 +238,58 @@ Furthermore, the pixel shortage is over. We want to see:
 * `grid` instead of `g`
 * `my_function_that_does_things` instead of `mftdt`
 
+Be sure to write documentation!
+-------------------------------
+
+Documentation isn't just good, it's great - and necessary with large packages
+like OAuthlib. Please make sure the next person who reads your function/method
+can quickly understand what it does and how. Also, please ensure the parameters
+passed to each function are properly documented as well.
+
+The project has these goals/requests for docstrings that are designed to make
+the autogenerated documentation read more cleanly:
+
+#. Every parameter in the function should be listed in the docstring, and
+   should appear in the same order as they appear in the function itself.
+#. If you are unsure of the best wording for a parameter description, leave it
+   blank, but still include the `:param foo:` line. This will make it easier for
+   maintainers to see and edit.
+#. Use an existing standardized description of a parameter that appears
+   elsewhere in this project's documentation whenever possible. For example,
+   `request` is used as a parameter throughout the project with the description
+   "OAuthlib request." - there is no reason to describe it differently in your
+   function. Parameter descriptions should be a sentence that ends with a
+   period - even if it is just two words.
+#. When possible, include a `type` declaration for the parameter. For example,
+   a "request" param is often accompanied with `:type request: oauthlib.common.Request`.
+   The type is expected to be an object type reference, and should never end
+   in a period.
+#. If there is a textual docstring (recommended), use a single blank line to
+   separate the docstring and the params.
+#. When you cite class functions, please use backticks.
+
+Consolidated example
+
+	def foo(self, request, client, bar=None, key=None):
+		"""
+		This method checks the `key` against the `client`. The `request` is
+		passed to maintain context.
+
+		Example MAC Authorization header, linebreaks added for clarity
+
+		Authorization: MAC id="h480djs93hd8",
+						   nonce="1336363200:dj83hs9s",
+						   mac="bhCQXTVyfj5cmA9uKkPFx1zeOXM="
+
+		.. _`MAC Access Authentication`: https://tools.ietf.org/html/draft-ietf-oauth-v2-http-mac-01
+		
+		:param request: OAuthlib request.
+		:type request: oauthlib.common.Request
+        :param client: Client object set by you, see ``.authenticate_client``.
+		:param bar:
+	    :param key: MAC given provided by token endpoint.
+		"""
+
 How pull requests are checked, tested, and done
 ===============================================
 
diff --git a/docs/index.rst b/docs/index.rst
index 1da2ca5..b6ce191 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,14 +7,14 @@ Welcome to OAuthLib's documentation!
 ====================================
 
 If you can't find what you need or have suggestions for improvement, don't
-hesitate to open a `new issue on GitHub`_!  
+hesitate to open a `new issue on GitHub`_!
 
 Check out :doc:`error_reporting` for details on how to be an awesome bug reporter.
 
-For news and discussions please head over to our `G+ OAuthLib community`_.
+For news and discussions please head over to our `Gitter OAuthLib community`_.
 
 .. _`new issue on GitHub`: https://github.com/oauthlib/oauthlib/issues/new
-.. _`G+ OAuthLib community`: https://plus.google.com/communities/101889017375384052571
+.. _`Gitter OAuthLib community`: https://gitter.im/oauthlib/Lobby
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/installation.rst b/docs/installation.rst
index 48e4288..72d7b08 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -9,7 +9,7 @@ For various reasons you may wish to install using your OS packaging system and
 install instructions for a few are shown below. Please send a PR to add a
 missing one.
 
-Latest release on PYPI
+Latest release on PyPI
 ----------------------
 
 
diff --git a/docs/oauth2/endpoints/endpoints.rst b/docs/oauth2/endpoints/endpoints.rst
index 80d5fbe..98599e8 100644
--- a/docs/oauth2/endpoints/endpoints.rst
+++ b/docs/oauth2/endpoints/endpoints.rst
@@ -24,7 +24,7 @@ handles user authorization, the token endpoint which provides tokens and the
 resource endpoint which provides access to protected resources. It is to the
 endpoints you will feed requests and get back an almost complete response. This
 process is simplified for you using a decorator such as the django one described
-later (but it's applicable to all other web frameworks librairies).
+later (but it's applicable to all other web frameworks libraries).
 
 The main purpose of the endpoint in OAuthLib is to figure out which grant type
 or token to dispatch the request to.