First pass at autodoc support (#464)

* First pass at autodoc support * Add mkautodoc requirement for docs builds * Linting * pip install httpx when building docs, to make it available to mkautodoc * Fix code example in docstring slightly * Use latest mkautodoc to resolve rendering of code snippets in docstrings * Fill in 'Helper functions' API docs * First pass at documenting Client * Add autodoc for Client * Update to mkautodoc 0.1 * Fix typos
encode · Oct 30, 2019 · 1ce3cc3 · 1ce3cc3
1 parent e3140a0
commit 1ce3cc3
Show file tree

Hide file tree

Showing 6 changed files with 290 additions and 33 deletions.
diff --git a/docs/api.md b/docs/api.md
@@ -8,40 +8,35 @@
     enable HTTP/2 and connection pooling for more efficient and
     long-lived connections.
 
-* `get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `post(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `put(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `patch(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `delete(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `request(method, url, [data], [files], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `build_request(method, url, [data], [files], [json], [params], [headers], [cookies])`
+::: httpx.request
+    :docstring:
 
-## `Client`
+::: httpx.get
+    :docstring:
 
-*An HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc.*
+::: httpx.options
+    :docstring:
 
-```python
->>> with httpx.Client() as client:
-...   response = client.get('https://example.org')
-```
+::: httpx.head
+    :docstring:
 
-* `def __init__([auth], [params], [headers], [cookies], [verify], [cert], [timeout], [pool_limits], [max_redirects], [app], [dispatch])`
-* `.params` - **QueryParams**
-* `.headers` - **Headers**
-* `.cookies` - **Cookies**
-* `def .get(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .options(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .head(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .post(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .put(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .patch(url, [data], [files], [json], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .delete(url, [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .request(method, url, [data], [files], [params], [headers], [cookies], [auth], [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .build_request(method, url, [data], [files], [json], [params], [headers], [cookies])`
-* `def .send(request, [stream], [allow_redirects], [verify], [cert], [timeout], [proxies])`
-* `def .close()`
+::: httpx.post
+    :docstring:
+
+::: httpx.put
+    :docstring:
+
+::: httpx.patch
+    :docstring:
+
+::: httpx.delete
+    :docstring:
+
+## `Client`
+
+::: httpx.Client
+    :docstring:
+    :members: headers cookies params request get head options post put patch delete build_request send close 
 
 ## `Response`
 

diff --git a/docs/css/custom.css b/docs/css/custom.css
@@ -0,0 +1,10 @@
+div.autodoc-docstring {
+  padding-left: 20px;
+  margin-bottom: 30px;
+  border-left: 5px solid rgba(230, 230, 230);
+}
+
+div.autodoc-members {
+  padding-left: 20px;
+  margin-bottom: 15px;
+}
diff --git a/httpx/api.py b/httpx/api.py
@@ -32,6 +32,51 @@ def request(
     stream: bool = False,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends an HTTP request.
+
+    **Parameters:**
+
+    * **method** - HTTP method for the new `Request` object: `GET`, `OPTIONS`,
+    `HEAD`, `POST`, `PUT`, `PATCH`, or `DELETE`.
+    * **url** - URL for the new `Request` object.
+    * **params** - *(optional)* Query parameters to include in the URL, as a
+    string, dictionary, or list of two-tuples.
+    * **data** - *(optional)* Data to include in the body of the request, as a
+    dictionary
+    * **files** - *(optional)* A dictionary of upload files to include in the
+    body of the request.
+    * **json** - *(optional)* A JSON serializable object to include in the body
+    of the request.
+    * **headers** - *(optional)* Dictionary of HTTP headers to include in the
+    request.
+    * **cookies** - *(optional)* Dictionary of Cookie items to include in the
+    request.
+    * **auth** - *(optional)* An authentication class to use when sending the
+    request.
+    * **timeout** - *(optional)* The timeout configuration to use when sending
+    the request.
+    * **allow_redirects** - *(optional)* Enables or disables HTTP redirects.
+    * **cert** - *(optional)* Either a path to an SSL certificate file, or
+    two-tuple of (certificate file, key file), or a three-tuple of (certificate
+    file, key file, password).
+    * **verify** - *(optional)* Enables or disables SSL verification.
+    * **trust_env** - *(optional)* Enables or disables usage of environment
+    variables for configuration.
+    * **proxies** - *(optional)* A dictionary mapping HTTP protocols to proxy
+    URLs.
+
+    **Returns:** `Response`
+
+    Usage:
+
+    ```
+    >>> import httpx
+    >>> response = httpx.request('GET', 'https://httpbin.org/get')
+    >>> response
+    <Response [200 OK]>
+    ```
+    """
     with Client(http_versions=["HTTP/1.1"]) as client:
         return client.request(
             method=method,
@@ -66,6 +111,14 @@ def get(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `GET` request.
+
+    **Parameters**: See `httpx.request`.
+
+    Note that the `data`, `files`, and `json` parameters are not available on
+    this function, as `GET` requests should not include a request body.
+    """
     return request(
         "GET",
         url,
@@ -96,6 +149,14 @@ def options(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends an `OPTIONS` request.
+
+    **Parameters**: See `httpx.request`.
+
+    Note that the `data`, `files`, and `json` parameters are not available on
+    this function, as `OPTIONS` requests should not include a request body.
+    """
     return request(
         "OPTIONS",
         url,
@@ -126,6 +187,16 @@ def head(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `HEAD` request.
+
+    **Parameters**: See `httpx.request`.
+
+    Note that the `data`, `files`, and `json` parameters are not available on
+    this function, as `HEAD` requests should not include a request body. The
+    `HEAD` method also differs from the other cases in that `allow_redirects`
+    defaults to `False`.
+    """
     return request(
         "HEAD",
         url,
@@ -159,6 +230,11 @@ def post(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `POST` request.
+
+    **Parameters**: See `httpx.request`.
+    """
     return request(
         "POST",
         url,
@@ -195,6 +271,11 @@ def put(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `PUT` request.
+
+    **Parameters**: See `httpx.request`.
+    """
     return request(
         "PUT",
         url,
@@ -231,6 +312,11 @@ def patch(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `PATCH` request.
+
+    **Parameters**: See `httpx.request`.
+    """
     return request(
         "PATCH",
         url,
@@ -264,6 +350,14 @@ def delete(
     timeout: TimeoutTypes = None,
     trust_env: bool = None,
 ) -> Response:
+    """
+    Sends a `DELETE` request.
+
+    **Parameters**: See `httpx.request`.
+
+    Note that the `data`, `files`, and `json` parameters are not available on
+    this function, as `DELETE` requests should not include a request body.
+    """
     return request(
         "DELETE",
         url,