Merge pull request #409 from twisted/rtd-shiny

Shinier documentation

Author: glyph

CHANGELOG.rst

@@ -26,7 +26,7 @@ Features
 --------
 
 - treq now ships type annotations. (`#366 <https://github.com/twisted/treq/issues/366>`__)
-- The new :mod:`treq.cookies` module provides helper functions for working with `http.cookiejar.Cookie` and `CookieJar` objects. (`#384 <https://github.com/twisted/treq/issues/384>`__)
+- The new :mod:`treq.cookies` module provides helper functions for working with `http.cookiejar.Cookie` and :class:`~http.cookiejar.CookieJar` objects. (`#384 <https://github.com/twisted/treq/issues/384>`__)
 - Python 3.13 is now supported. (`#391 <https://github.com/twisted/treq/issues/391>`__)
 
 
@@ -40,7 +40,7 @@ Deprecations and Removals
 -------------------------
 
 - Mixing the *json* argument with *files* or *data* now raises `TypeError`. (`#297 <https://github.com/twisted/treq/issues/297>`__)
-- Passing non-string (`str` or `bytes`) values as part of a dict to the *headers* argument now results in a `TypeError`, as does passing any collection other than a `dict` or `Headers` instance. (`#302 <https://github.com/twisted/treq/issues/302>`__)
+- Passing non-string (`str` or `bytes`) values as part of a dict to the *headers* argument now results in a `TypeError`, as does passing any collection other than a `dict` or :class:`~twisted.web.http.http_headers.Headers` instance. (`#302 <https://github.com/twisted/treq/issues/302>`__)
 - Support for Python 3.7 and PyPy 3.8, which have reached end of support, has been dropped. (`#378 <https://github.com/twisted/treq/issues/378>`__)
 
 

README.rst

@@ -24,8 +24,8 @@ treq: High-level Twisted HTTP Client API
 
 ``treq`` is an HTTP library inspired by
 `requests <https://requests.readthedocs.io/>`_ but written on top of
-`Twisted <https://www.twistedmatrix.com>`_'s
-`Agents <https://twistedmatrix.com/documents/current/api/twisted.web.client.Agent.html>`_.
+`Twisted <https://twisted.org/>`_'s
+`Agents <https://docs.twisted.org/en/stable/api/twisted.web.client.Agent.html>`_.
 
 It provides a simple, higher level API for making HTTP requests when
 using Twisted.

changelog.d/409.doc.rst

@@ -0,0 +1 @@
+Update documentation to use `async`/`await` syntax

docs/conf.py

@@ -26,13 +26,18 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
+extensions = [
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_rtd_theme",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -92,12 +97,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "sphinx_rtd_theme"
+
+# https://docs.readthedocs.com/platform/stable/intro/sphinx.html#set-the-canonical-url
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {"flyout_display": "attached"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/examples/_utils.py

@@ -1,10 +1,7 @@
-from __future__ import print_function
-
 import treq
 
 
-def print_response(response):
+async def print_response(response):
     print(response.code, response.phrase)
     print(response.headers)
-
-    return treq.text_content(response).addCallback(print)
+    print(await treq.text_content(response))

docs/examples/basic_auth.py

@@ -1,15 +1,15 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get(
-        'https://httpbin.org/basic-auth/treq/treq',
-        auth=('treq', 'treq')
+async def basic_auth(reactor):
+    resp = await treq.get(
+        "https://httpbin.org/basic-auth/treq/treq",
+        auth=("treq", "treq"),
     )
-    d.addCallback(print_response)
-    return d
+    await print_response(resp)
+
 
-react(main, [])
+react(basic_auth)

docs/examples/basic_get.py

@@ -1,12 +1,13 @@
 from twisted.internet.task import react
-from _utils import print_response
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get('https://httpbin.org/get')
-    d.addCallback(print_response)
-    return d
+async def basic_get(reactor):
+    resp = await treq.get("https://httpbin.org/get")
+    print(resp.code, resp.phrase)
+    print(resp.headers)
+    print(await resp.text())
 
-react(main, [])
+
+react(basic_get)

docs/examples/basic_post.py

@@ -1,13 +1,15 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor):
-    d = treq.post("https://httpbin.org/post",
-                  data={"form": "data"})
-    d.addCallback(print_response)
-    return d
+def basic_post(reactor):
+    resp = await treq.post(
+        "https://httpbin.org/post",
+        data={"form": "data"},
+    )
+    await print_response(resp)
+
 
-react(main, [])
+react(basic_post)

docs/examples/basic_url.py

@@ -1,17 +1,18 @@
-# -*- encoding: utf-8 -*-
+from _utils import print_response
 from hyperlink import DecodedURL
 from twisted.internet.task import react
-from _utils import print_response
 
 import treq
 
-def main(reactor):
+
+async def basic_url(reactor):
     url = (
-        DecodedURL.from_text(u"https://httpbin.org")
-        .child(u"get")      # add path /get
-        .add(u"foo", u"&")  # add query ?foo=%26
+        DecodedURL.from_text("https://httpbin.org")
+        .child("get")  # add path /get
+        .add("foo", "&")  # add query ?foo=%26
     )
     print(url.to_text())
-    return treq.get(url).addCallback(print_response)
+    await print_response(await treq.get(url))
+
 
-react(main, [])
+react(basic_url)

docs/examples/custom_agent.py

@@ -1,19 +1,18 @@
-from treq.client import HTTPClient
 from _utils import print_response
 from twisted.internet.task import react
 from twisted.web.client import Agent
 
-def make_custom_agent(reactor):
-    return Agent(reactor, connectTimeout=42)
+from treq.client import HTTPClient
+
 
-def main(reactor, *args):
-    agent = make_custom_agent(reactor)
-    http_client = HTTPClient(agent)
-    d = http_client.get(
-        'https://secure.example.net/area51',
-        auth=('admin', "you'll never guess!"))
-    d.addCallback(print_response)
-    return d
+async def custom_agent(reactor):
+    my_agent = Agent(reactor, connectTimeout=42)
+    http_client = HTTPClient(my_agent)
+    resp = await http_client.get(
+        "https://secure.example.net/area51",
+        auth=("admin", "you'll never guess!"),
+    )
+    await print_response(resp)
 
-react(main, [])
 
+react(custom_agent)