Migrate docs to Sphinx + MyST

Author: florimondmanca

docs/api.md

@@ -2,55 +2,68 @@
 
 ## Async API Overview
 
+### Base interfaces
+
 The `AsyncHTTPTransport` and `AsyncByteStream` classes provide the base
 interface which transport classes need to implement.
 
-::: httpcore.AsyncHTTPTransport
-    :docstring:
-    :members: arequest aclose
+<!-- See: https://myst-parser.readthedocs.io/en/latest/using/howto.html#use-sphinx-ext-autodoc-in-markdown-files -->
+
+```{eval-rst}
+.. autoclass:: httpcore.AsyncHTTPTransport
+    :members: arequest, aclose
 
-::: httpcore.AsyncByteStream
-    :docstring:
-    :members: __aiter__ aclose
+.. autoclass:: httpcore.AsyncByteStream
+    :members: __aiter__, aclose
+```
 
-The `AsyncConnectionPool` class is a concrete implementation of `AsyncHTTPTransport`.
+### Connection pool
 
-::: httpcore.AsyncConnectionPool
-    :docstring:
+The {class}`AsyncConnectionPool <httpcore.AsyncConnectionPool>` class is a concrete implementation of {class}`AsyncHTTPTransport <httpcore.AsyncHTTPTransport>`.
 
+```{eval-rst}
+.. autoclass:: httpcore.AsyncConnectionPool
+```
 
-The `PlainByteStream` and `AsyncIteratorByteStream` classes are concrete implementations of `AsyncByteStream`.
+### Byte streams
 
-::: httpcore.PlainByteStream
-    :docstring:
+The {class}`PlainByteStream <httpcore.PlainByteStream>` and {class}`AsyncIteratorByteStream <httpcore.AsyncIteratorByteStream>` classes are concrete implementations of `AsyncByteStream`.
 
-::: httpcore.AsyncIteratorByteStream
-    :docstring:
+```{eval-rst}
+.. autoclass:: httpcore.PlainByteStream
 
----
+.. autoclass:: httpcore.AsyncIteratorByteStream
+```
 
 ## Sync API Overview
 
-The `SyncHTTPTransport` and `SyncByteStream` classes provide the base
-interface which transport classes need to implement.
+### Base interfaces
+
+The {class}`SyncHTTPTransport <httpcore.SyncHTTPTransport>` and {class}`SyncByteStream <httpcore.SyncByteStream>` classes provide the base interface which transport classes need to implement.
+
+```{eval-rst}
+.. autoclass:: httpcore.SyncHTTPTransport
+    :members: request, close
+
+.. autoclass:: httpcore.SyncByteStream
+    :members: __iter__, close
+```
 
-::: httpcore.SyncHTTPTransport
-    :docstring:
-    :members: request close
+### Connection pool
 
-::: httpcore.SyncByteStream
-    :docstring:
-    :members: __iter__ close
+The {class}`SyncConnectionPool <httpcore.SyncConnectionPool>` class is a concrete implementation of {class}`SyncHTTPTransport <httpcore.SyncHTTPTransport>`.
 
-The `SyncConnectionPool` class is a concrete implementation of `SyncHTTPTransport`.
+```{eval-rst}
+.. autoclass:: httpcore.SyncConnectionPool
+```
 
-::: httpcore.SyncConnectionPool
-    :docstring:
+### Byte streams
 
-The `PlainByteStream` and `IteratorByteStream` classes are concrete implementations of `SyncByteStream`.
+The {class}`PlainByteStream <httpcore.PlainByteStream>` and {class}`IteratorByteStream <httpcore.IteratorByteStream>` classes are concrete implementations of `SyncByteStream`.
 
-::: httpcore.PlainByteStream
-    :docstring:
+```{eval-rst}
+.. autoclass:: httpcore.PlainByteStream
+    :noindex:
 
-::: httpcore.IteratorByteStream
-    :docstring:
+.. autoclass:: httpcore.IteratorByteStream
+```

docs/conf.py

@@ -0,0 +1,53 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = "HTTPCore"
+copyright = "2021, Encode"
+author = "Encode"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+
+# Prevent sphinx-autodoc from ordering autodoc members alphabetically.
+# Instead use whichever order is defined by :members:.
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_member_order
+autodoc_member_order = "bysource"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []

docs/css/custom.css

@@ -1,89 +1,21 @@
-# HTTP Core
-
-[![Test Suite](https://github.com/encode/httpcore/workflows/Test%20Suite/badge.svg)](https://github.com/encode/httpcore/actions)
-[![Package version](https://badge.fury.io/py/httpcore.svg)](https://pypi.org/project/httpcore/)
-
-> *Do one thing, and do it well.*
-
-The HTTP Core package provides a minimal low-level HTTP client, which does
-one thing only. Sending HTTP requests.
-
-It does not provide any high level model abstractions over the API,
-does not handle redirects, multipart uploads, building authentication headers,
-transparent HTTP caching, URL parsing, session cookie handling,
-content or charset decoding, handling JSON, environment based configuration
-defaults, or any of that Jazz.
-
-Some things HTTP Core does do:
-
-* Sending HTTP requests.
-* Provides both sync and async interfaces.
-* Supports HTTP/1.1 and HTTP/2.
-* Async backend support for `asyncio`, `trio` and `curio`.
-* Automatic connection pooling.
-* HTTP(S) proxy support.
-
-## Installation
-
-For HTTP/1.1 only support, install with...
-
-```shell
-$ pip install httpcore
-```
-
-For HTTP/1.1 and HTTP/2 support, install with...
-
-```shell
-$ pip install httpcore[http2]
+```{include} ../README.md
 ```
 
-## Quickstart
-
-Here's an example of making an HTTP GET request using `httpcore`...
+<!-- Table of Content entries, shown in left sidebar. -->
 
-```python
-with httpcore.SyncConnectionPool() as http:
-    status_code, headers, stream, ext = http.request(
-        method=b'GET',
-        url=(b'https', b'example.org', 443, b'/'),
-        headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')]
-    )
+```{toctree}
+:hidden:
+:caption: Usage
 
-    try:
-        body = b''.join([chunk for chunk in stream])
-    finally:
-        stream.close()
-
-    print(status_code, body)
+api
 ```
 
-Or, using async...
-
-```python
-async with httpcore.AsyncConnectionPool() as http:
-    status_code, headers, stream, ext = await http.arequest(
-        method=b'GET',
-        url=(b'https', b'example.org', 443, b'/'),
-        headers=[(b'host', b'example.org'), (b'user-agent', 'httpcore')]
-    )
+```{toctree}
+:hidden:
+:caption: Development
 
-    try:
-        body = b''.join([chunk async for chunk in stream])
-    finally:
-        await stream.aclose()
-
-    print(status_code, body)
+contributing
+Changelog <https://github.com/encode/httpcore/blob/master/CHANGELOG.md>
+License <https://github.com/encode/httpcore/blob/master/LICENSE.md>
+Source Code <https://github.com/encode/httpcore>
 ```
-
-## Motivation
-
-You probably don't want to be using HTTP Core directly. It might make sense if
-you're writing something like a proxy service in Python, and you just want
-something at the lowest possible level, but more typically you'll want to use
-a higher level client library, such as `httpx`.
-
-The motivation for `httpcore` is:
-
-* To provide a reusable low-level client library, that other packages can then build on top of.
-* To provide a *really clear interface split* between the networking code and client logic,
-  so that each is easier to understand and reason about in isolation.

docs/index.md

@@ -37,7 +37,7 @@ class AsyncByteStream:
     The base interface for request and response bodies.
 
     Concrete implementations should subclass this class, and implement
-    the `\\__aiter__` method, and optionally the `aclose` method.
+    the :meth:`__aiter__` method, and optionally the :meth:`aclose` method.
     """
 
     async def __aiter__(self) -> AsyncIterator[bytes]:
@@ -57,8 +57,8 @@ class AsyncHTTPTransport:
     """
     The base interface for sending HTTP requests.
 
-    Concete implementations should subclass this class, and implement
-    the `request` method, and optionally the `close` method.
+    Concrete implementations should subclass this class, and implement
+    the :meth:`arequest` method, and optionally the :meth:`aclose` method.
     """
 
     async def arequest(
@@ -72,25 +72,29 @@ async def arequest(
         """
         The interface for sending a single HTTP request, and returning a response.
 
-        **Parameters:**
-
-        * **method** - `bytes` - The HTTP method, such as `b'GET'`.
-        * **url** - `Tuple[bytes, bytes, Optional[int], bytes]` - The URL as a 4-tuple
-        of (scheme, host, port, path).
-        * **headers** - `Optional[List[Tuple[bytes, bytes]]]` - Any HTTP headers
-        to send with the request.
-        * **stream** - `Optional[AsyncByteStream]` - The body of the HTTP request.
-        * **ext** - `Optional[dict]` - A dictionary of optional extensions.
-
-        ** Returns:**
-
-        A four-tuple of:
-
-        * **status_code** - `int` - The HTTP status code, such as `200`.
-        * **headers** - `List[Tuple[bytes, bytes]]` - Any HTTP headers included
-        on the response.
-        * **stream** - `AsyncByteStream` - The body of the HTTP response.
-        * **ext** - `dict` - A dictionary of optional extensions.
+        Parameters
+        ----------
+        method: bytes
+            The HTTP method, such as `b'GET'`.
+        url: Tuple[bytes, bytes, Optional[int], bytes]
+            The URL as a 4-tuple of (scheme, host, port, path).
+        headers: List[Tuple[bytes, bytes]]
+            Any HTTP headers to send with the request.
+        stream: :class:`AsyncByteStream`
+            The body of the HTTP request.
+        ext: dict
+            A dictionary of optional extensions.
+
+        Returns
+        -------
+        status_code: int
+            The HTTP status code, such as `200`.
+        headers: List[Tuple[bytes, bytes]]
+            Any HTTP headers included on the response.
+        stream: :class:`AsyncByteStream`
+            The body of the HTTP response.
+        ext: dict
+            A dictionary of optional extensions.
         """
         raise NotImplementedError()  # pragma: nocover
 

httpcore/_async/base.py

@@ -77,26 +77,30 @@ class AsyncConnectionPool(AsyncHTTPTransport):
     """
     A connection pool for making HTTP requests.
 
-    **Parameters:**
-
-    * **ssl_context** - `Optional[SSLContext]` - An SSL context to use for
-    verifying connections.
-    * **max_connections** - `Optional[int]` - The maximum number of concurrent
-    connections to allow.
-    * **max_keepalive_connections** - `Optional[int]` - The maximum number of
-    connections to allow before closing keep-alive connections.
-    * **keepalive_expiry** - `Optional[float]` - The maximum time to allow
-    before closing a keep-alive connection.
-    * **http2** - `bool` - Enable HTTP/2 support.
-    * **uds** - `str` - Path to a Unix Domain Socket to use instead of TCP sockets.
-    * **local_address** - `Optional[str]` - Local address to connect from. Can
-    also be used to connect using a particular address family. Using
-    `local_address="0.0.0.0"` will connect using an `AF_INET` address (IPv4),
-    while using `local_address="::"` will connect using an `AF_INET6` address
-    (IPv6).
-    * **retries** - `int` - The maximum number of retries when trying to establish a
-    connection.
-    * **backend** - `str` - A name indicating which concurrency backend to use.
+    Parameters
+    ----------
+    ssl_context: Optional[SSLContext]
+        An SSL context to use for verifying connections.
+    max_connections: Optional[int]
+        The maximum number of concurrent connections to allow.
+    max_keepalive_connections: Optional[int]
+        The maximum number of connections to allow before closing keep-alive
+        connections.
+    keepalive_expiry: Optional[float]
+        The maximum time to allow before closing a keep-alive connection.
+    http2: bool
+        Enable HTTP/2 support.
+    uds: str
+        Path to a Unix Domain Socket to use instead of TCP sockets.
+    local_address: Optional[str]
+        Local address to connect from. Can also be used to connect using a particular
+        address family. Using `local_address="0.0.0.0"` will connect using an `AF_INET`
+        address (IPv4), while using `local_address="::"` will connect using an
+        `AF_INET6` address (IPv6).
+    retries: int
+        The maximum number of retries when trying to establish a connection.
+    backend: str
+        A name indicating which concurrency backend to use.
     """
 
     def __init__(