start using google-style docstrings

3 files changed, 36 insertions, 27 deletions

diff --git a/docs/source/api.rst b/docs/source/api.rst
index c29f582..8cca31d 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -51,8 +51,7 @@ activate
 httprettified
 -------------
 
-.. autoclass:: httpretty.core.httprettified
-   :members:
+.. autofunction:: httpretty.core.httprettified
 
 
 .. _enabled:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0dea7ef..0218a7e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -15,7 +15,7 @@ from httpretty.version import version # noqa
 
 
 project = 'HTTPretty'
-copyright = '2018, Gabriel Falcao'
+copyright = '2020, Gabriel Falcao'
 author = 'Gabriel Falcao'
 
 # The short X.Y version
@@ -25,6 +25,7 @@ release = version
 
 
 extensions = [
+    'sphinx.ext.napoleon',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
@@ -79,6 +80,6 @@ intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
 
     'httplib2': ('https://httplib2.readthedocs.io/en/latest/', None),
-    'requests': ('http://docs.python-requests.org/en/master/', None),
+    'requests': ('https://requests.readthedocs.io/en/master/', None),
     'urllib3': ('https://urllib3.readthedocs.io/en/latest/', None),
 }
diff --git a/httpretty/core.py b/httpretty/core.py
index 5edd4d7..a8dde8e 100644
--- a/httpretty/core.py
+++ b/httpretty/core.py
@@ -40,6 +40,7 @@ import traceback
 import warnings
 
 from functools import partial
+from typing import Callable
 
 from .compat import (
     BaseClass,
@@ -762,16 +763,20 @@ class Entry(BaseClass):
     stored in memory as internal representation of a HTTP
     request/response definition.
 
-    :param method: string
-    :param uri: string
-    :param body: string
-    :param adding_headers: dict - headers to be added to the response
-    :param forcing_headers: dict - headers to be forcefully set in the response
-    :param status: an integer (e.g.: ``status=200``)
-    :param streaming: bool - whether to stream the response
-    :param headers: keyword-args with headers to be added to the response
+    Args:
+        method (str): One of ``httpretty.GET``, ``httpretty.PUT``, ``httpretty.POST``, ``httpretty.DELETE``, ``httpretty.HEAD``, ``httpretty.PATCH``, ``httpretty.OPTIONS``, ``httpretty.CONNECT``.
+        uri (str|re.Pattern): The URL to match
+        adding_headers (dict): Extra headers to be added to the response
+        forcing_headers (dict): Overwrite response headers.
+        status (int): The status code for the response, defaults to ``200``.
+        streaming (bool): Whether should stream the response into chunks via generator.
+        headers: Headers to inject in the faked response.
 
-    .. warning:: When using the ``forcing_headers`` option make sure to add the header ``Content-Length`` otherwise calls using :py:mod:`requests` will try to load the response endlessly.
+    Returns:
+        httpretty.Entry: containing the request-matching metadata.
+
+
+    .. warning:: When using the ``forcing_headers`` option make sure to add the header ``Content-Length`` to match at most the total body length, otherwise some HTTP clients can hang indefinitely.
     """
     def __init__(self, method, uri, body,
                  adding_headers=None,
@@ -1449,7 +1454,6 @@ class httpretty(HttpBaseClass):
 
            assert httpretty.latest_requests[-1].url == 'https://httpbin.org/ip'
 
-
         :param method: one of ``httpretty.GET``, ``httpretty.PUT``, ``httpretty.POST``, ``httpretty.DELETE``, ``httpretty.HEAD``, ``httpretty.PATCH``, ``httpretty.OPTIONS``, ``httpretty.CONNECT``
         :param uri: a string or regex pattern (e.g.: **"https://httpbin.org/ip"**)
         :param body: a string, defaults to ``{"message": "HTTPretty :)"}``
@@ -1504,19 +1508,24 @@ class httpretty(HttpBaseClass):
             status=200,
             streaming=False,
             **kw):
-        """
-        shortcut to create an :py:class:`~httpretty.core.Entry` that takes the body as first positional argument
-
-        .. seealso:: the parameters of this function match those of the :py:class:`~httpretty.core.Entry` constructor
-        :param body:
-        :param method: one of ``httpretty.GET``, ``httpretty.PUT``, ``httpretty.POST``, ``httpretty.DELETE``, ``httpretty.HEAD``, ``httpretty.PATCH``, ``httpretty.OPTIONS``, ``httpretty.CONNECT``
-        :param uri:
-        :param adding_headers:
-        :param forcing_headers:
-        :param status: defaults to **200**
-        :param streaming: defaults to **False**
-        :param kw: keyword-arguments passed onto the :py:class:`~httpretty.core.Entry`
-        :returns: an :py:class:`~httpretty.core.Entry`
+        """Shortcut to create an :py:class:`~httpretty.core.Entry` that takes
+        the body as first positional argument.
+
+        .. seealso:: the parameters of this function match those of
+                     the :py:class:`~httpretty.core.Entry` constructor.
+
+        Args:
+            body (str): The body to return as response..
+            method (str): One of ``httpretty.GET``, ``httpretty.PUT``, ``httpretty.POST``, ``httpretty.DELETE``, ``httpretty.HEAD``, ``httpretty.PATCH``, ``httpretty.OPTIONS``, ``httpretty.CONNECT``.
+            uri (str|re.Pattern): The URL to match
+            adding_headers (dict): Extra headers to be added to the response
+            forcing_headers (dict): Overwrite **any** response headers, even "Content-Length".
+            status (int): The status code for the response, defaults to ``200``.
+            streaming (bool): Whether should stream the response into chunks via generator.
+            kwargs: Keyword-arguments are forwarded to :py:class:`~httpretty.core.Entry`
+
+        Returns:
+            httpretty.Entry: containing the request-matching metadata.
         """
         kw['body'] = body
         kw['adding_headers'] = adding_headers