diff --git a/docs/api.md b/docs/api.md index 3bbde423c..908eb8a54 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,55 +2,81 @@ ## Async API Overview -The `AsyncHTTPTransport` and `AsyncByteStream` classes provide the base -interface which transport classes need to implement. +### Base async interfaces -::: httpcore.AsyncHTTPTransport - :docstring: - :members: arequest aclose +These classes provide the base interface which transport classes need to implement. -::: httpcore.AsyncByteStream - :docstring: - :members: __aiter__ aclose +:::{eval-rst} +.. autoclass:: httpcore.AsyncHTTPTransport + :members: arequest, aclose -The `AsyncConnectionPool` class is a concrete implementation of `AsyncHTTPTransport`. +.. autoclass:: httpcore.AsyncByteStream + :members: __aiter__, aclose +::: -::: httpcore.AsyncConnectionPool - :docstring: +### Async connection pool +:::{eval-rst} +.. autoclass:: httpcore.AsyncConnectionPool + :show-inheritance: +::: -The `PlainByteStream` and `AsyncIteratorByteStream` classes are concrete implementations of `AsyncByteStream`. +### Async proxy -::: httpcore.PlainByteStream - :docstring: +:::{eval-rst} +.. autoclass:: httpcore.AsyncHTTPProxy + :show-inheritance: +::: -::: httpcore.AsyncIteratorByteStream - :docstring: +### Async byte streams ---- +These classes are concrete implementations of [`AsyncByteStream`](httpcore.AsyncByteStream). + +:::{eval-rst} +.. autoclass:: httpcore.PlainByteStream + :show-inheritance: + +.. autoclass:: httpcore.AsyncIteratorByteStream + :show-inheritance: +::: ## Sync API Overview -The `SyncHTTPTransport` and `SyncByteStream` classes provide the base -interface which transport classes need to implement. +### Base sync interfaces + +These 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 +::: + +### Sync connection pool -::: httpcore.SyncHTTPTransport - :docstring: - :members: request close +:::{eval-rst} +.. autoclass:: httpcore.SyncConnectionPool + :show-inheritance: +::: -::: httpcore.SyncByteStream - :docstring: - :members: __iter__ close +### Sync proxy -The `SyncConnectionPool` class is a concrete implementation of `SyncHTTPTransport`. +:::{eval-rst} +.. autoclass:: httpcore.SyncHTTPProxy + :show-inheritance: +::: -::: httpcore.SyncConnectionPool - :docstring: +### Sync byte streams -The `PlainByteStream` and `IteratorByteStream` classes are concrete implementations of `SyncByteStream`. +These classes are concrete implementations of [`SyncByteStream`](httpcore.SyncByteStream). -::: httpcore.PlainByteStream - :docstring: +:::{eval-rst} +.. autoclass:: httpcore.PlainByteStream + :show-inheritance: + :noindex: -::: httpcore.IteratorByteStream - :docstring: +.. autoclass:: httpcore.IteratorByteStream + :show-inheritance: +::: diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..e5f646c6c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,60 @@ +# See: https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -- + +import os +import sys + +# Allow sphinx-autodoc to access `httpcore` contents. +sys.path.insert(0, os.path.abspath(".")) + +# -- Project information -- + +project = "HTTPCore" +copyright = "2021, Encode" +author = "Encode" + +# -- General configuration -- + +extensions = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", +] + +myst_enable_extensions = [ + "colon_fence", +] + +# Preserve :members: order. +autodoc_member_order = "bysource" + +# Show type hints in descriptions, rather than signatures. +autodoc_typehints = "description" + +# -- HTML configuration -- + +html_theme = "furo" + +# -- App setup -- + + +def _viewcode_follow_imported(app, modname, attribute): + # We set `__module__ = "httpcore"` on all public attributes for prettier + # repr(), so viewcode needs a little help to find the original source modules. + + if modname != "httpcore": + return None + + import httpcore + + try: + # Set in httpcore/__init__.py + return getattr(httpcore, attribute).__source_module__ + except AttributeError: + return None + + +def setup(app): + app.connect("viewcode-follow-imported", _viewcode_follow_imported) diff --git a/docs/contributing.md b/docs/contributing.md index 0b42944fe..f87d48e33 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -97,9 +97,10 @@ To run the tests, use: $ scripts/test ``` -!!! warning - The test suite spawns testing servers on ports **8000** and **8001**. - Make sure these are not in use, so the tests can run properly. +:::{warning} +The test suite spawns testing servers on ports **8000** and **8001**. +Make sure these are not in use, so the tests can run properly. +::: You can run a single test script like this: diff --git a/docs/css/custom.css b/docs/css/custom.css deleted file mode 100644 index 6e5d91919..000000000 --- a/docs/css/custom.css +++ /dev/null @@ -1,10 +0,0 @@ -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/docs/index.md b/docs/index.md index 5178ada6b..29f3c54cf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,89 +1,21 @@ -# HTTP Core +:::{include} ../README.md +::: -[![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.* +:::{toctree} +:hidden: +:caption: Usage -The HTTP Core package provides a minimal low-level HTTP client, which does -one thing only. Sending HTTP requests. +api +::: -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. +:::{toctree} +:hidden: +:caption: Development -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] -``` - -## Quickstart - -Here's an example of making an HTTP GET request using `httpcore`... - -```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')] - ) - - try: - body = b''.join([chunk for chunk in stream]) - finally: - stream.close() - - print(status_code, body) -``` - -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')] - ) - - try: - body = b''.join([chunk async for chunk in stream]) - finally: - await stream.aclose() - - print(status_code, body) -``` - -## 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. +contributing +Changelog +License +Source Code +::: diff --git a/httpcore/__init__.py b/httpcore/__init__.py index 84e0ae4d7..18cd929f9 100644 --- a/httpcore/__init__.py +++ b/httpcore/__init__.py @@ -57,4 +57,7 @@ for _name in __all__: if not _name.startswith("__"): + # Save original source module, used by Sphinx. + __locals[_name].__source_module__ = __locals[_name].__module__ + # Override module for prettier repr(). setattr(__locals[_name], "__module__", "httpcore") # noqa diff --git a/httpcore/_async/base.py b/httpcore/_async/base.py index cf449f428..ca62e044c 100644 --- a/httpcore/_async/base.py +++ b/httpcore/_async/base.py @@ -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: + The HTTP method, such as ``b'GET'``. + url: + The URL as a 4-tuple of (scheme, host, port, path). + headers: + Any HTTP headers to send with the request. + stream: + The body of the HTTP request. + ext: + A dictionary of optional extensions. + + Returns + ------- + status_code: + The HTTP status code, such as ``200``. + headers: + Any HTTP headers included on the response. + stream: + The body of the HTTP response. + ext: + A dictionary of optional extensions. """ raise NotImplementedError() # pragma: nocover diff --git a/httpcore/_async/connection_pool.py b/httpcore/_async/connection_pool.py index 46ede0ba4..ce50f87ed 100644 --- a/httpcore/_async/connection_pool.py +++ b/httpcore/_async/connection_pool.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: + An SSL context to use for verifying connections. + max_connections: + The maximum number of concurrent connections to allow. + max_keepalive_connections: + The maximum number of connections to allow before closing keep-alive + connections. + keepalive_expiry: + The maximum time to allow before closing a keep-alive connection. + http2: + Enable HTTP/2 support. + uds: + Path to a Unix Domain Socket to use instead of TCP sockets. + local_address: + 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: + The maximum number of retries when trying to establish a connection. + backend: + A name indicating which concurrency backend to use. """ def __init__( diff --git a/httpcore/_async/http_proxy.py b/httpcore/_async/http_proxy.py index d9df762b0..f62179a69 100644 --- a/httpcore/_async/http_proxy.py +++ b/httpcore/_async/http_proxy.py @@ -41,21 +41,23 @@ class AsyncHTTPProxy(AsyncConnectionPool): """ A connection pool for making HTTP requests via an HTTP proxy. - **Parameters:** - - * **proxy_url** - `Tuple[bytes, bytes, Optional[int], bytes]` - The URL of - the proxy service as a 4-tuple of (scheme, host, port, path). - * **proxy_headers** - `Optional[List[Tuple[bytes, bytes]]]` - A list of - proxy headers to include. - * **proxy_mode** - `str` - A proxy mode to operate in. May be "DEFAULT", - "FORWARD_ONLY", or "TUNNEL_ONLY". - * **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. - * **http2** - `bool` - Enable HTTP/2 support. + Parameters + ---------- + proxy_url: + The URL of the proxy service as a 4-tuple of (scheme, host, port, path). + proxy_headers: + A list of proxy headers to include. + proxy_mode: + A proxy mode to operate in. May be "DEFAULT", "FORWARD_ONLY", or "TUNNEL_ONLY". + ssl_context: + An SSL context to use for verifying connections. + max_connections: + The maximum number of concurrent connections to allow. + max_keepalive_connections: + The maximum number of connections to allow before closing keep-alive + connections. + http2: + Enable HTTP/2 support. """ def __init__( diff --git a/httpcore/_bytestreams.py b/httpcore/_bytestreams.py index e938aaf90..2fffe5fb3 100644 --- a/httpcore/_bytestreams.py +++ b/httpcore/_bytestreams.py @@ -7,11 +7,15 @@ class PlainByteStream(AsyncByteStream, SyncByteStream): """ A concrete implementation for either sync or async byte streams. - Just handles a plain byte string as the content of the stream. - ``` - stream = httpcore.PlainByteStream(b"123") - ``` + Example:: + + stream = httpcore.PlainByteStream(b"123") + + Parameters + ---------- + content: + A plain byte string used as the content of the stream. """ def __init__(self, content: bytes) -> None: @@ -27,14 +31,21 @@ async def __aiter__(self) -> AsyncIterator[bytes]: class IteratorByteStream(SyncByteStream): """ A concrete implementation for sync byte streams. - Handles a byte iterator as the content of the stream. - ``` - def generate_content(): - ... + Example:: + + def generate_content(): + yield b"Hello, world!" + ... - stream = httpcore.IteratorByteStream(generate_content()) - ``` + stream = httpcore.IteratorByteStream(generate_content()) + + Parameters + ---------- + iterator: + A sync byte iterator, used as the content of the stream. + close_func: + An optional function called when closing the stream. """ def __init__(self, iterator: Iterator[bytes], close_func: Callable = None) -> None: @@ -53,14 +64,21 @@ def close(self) -> None: class AsyncIteratorByteStream(AsyncByteStream): """ A concrete implementation for async byte streams. - Handles an async byte iterator as the content of the stream. - ``` - async def generate_content(): - ... + Example:: + + async def generate_content(): + yield b"Hello, world!" + ... + + stream = httpcore.AsyncIteratorByteStream(generate_content()) - stream = httpcore.AsyncIteratorByteStream(generate_content()) - ``` + Parameters + ---------- + aiterator: + An async byte iterator, used as the content of the stream. + aclose_func: + An optional async function called when closing the stream. """ def __init__( diff --git a/httpcore/_sync/base.py b/httpcore/_sync/base.py index 95a434eb0..5c4d16b8e 100644 --- a/httpcore/_sync/base.py +++ b/httpcore/_sync/base.py @@ -37,7 +37,7 @@ class SyncByteStream: The base interface for request and response bodies. Concrete implementations should subclass this class, and implement - the `\\__iter__` method, and optionally the `close` method. + the :meth:`__iter__` method, and optionally the :meth:`close` method. """ def __iter__(self) -> Iterator[bytes]: @@ -57,8 +57,8 @@ class SyncHTTPTransport: """ 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:`request` method, and optionally the :meth:`close` method. """ def request( @@ -72,25 +72,29 @@ def request( """ 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[SyncByteStream]` - 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** - `SyncByteStream` - The body of the HTTP response. - * **ext** - `dict` - A dictionary of optional extensions. + Parameters + ---------- + method: + The HTTP method, such as ``b'GET'``. + url: + The URL as a 4-tuple of (scheme, host, port, path). + headers: + Any HTTP headers to send with the request. + stream: + The body of the HTTP request. + ext: + A dictionary of optional extensions. + + Returns + ------- + status_code: + The HTTP status code, such as ``200``. + headers: + Any HTTP headers included on the response. + stream: + The body of the HTTP response. + ext: + A dictionary of optional extensions. """ raise NotImplementedError() # pragma: nocover diff --git a/httpcore/_sync/connection_pool.py b/httpcore/_sync/connection_pool.py index 4702184b8..ce63f03fe 100644 --- a/httpcore/_sync/connection_pool.py +++ b/httpcore/_sync/connection_pool.py @@ -77,26 +77,30 @@ class SyncConnectionPool(SyncHTTPTransport): """ 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: + An SSL context to use for verifying connections. + max_connections: + The maximum number of concurrent connections to allow. + max_keepalive_connections: + The maximum number of connections to allow before closing keep-alive + connections. + keepalive_expiry: + The maximum time to allow before closing a keep-alive connection. + http2: + Enable HTTP/2 support. + uds: + Path to a Unix Domain Socket to use instead of TCP sockets. + local_address: + 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: + The maximum number of retries when trying to establish a connection. + backend: + A name indicating which concurrency backend to use. """ def __init__( diff --git a/httpcore/_sync/http_proxy.py b/httpcore/_sync/http_proxy.py index f5576c010..2bc66ac0a 100644 --- a/httpcore/_sync/http_proxy.py +++ b/httpcore/_sync/http_proxy.py @@ -41,21 +41,23 @@ class SyncHTTPProxy(SyncConnectionPool): """ A connection pool for making HTTP requests via an HTTP proxy. - **Parameters:** - - * **proxy_url** - `Tuple[bytes, bytes, Optional[int], bytes]` - The URL of - the proxy service as a 4-tuple of (scheme, host, port, path). - * **proxy_headers** - `Optional[List[Tuple[bytes, bytes]]]` - A list of - proxy headers to include. - * **proxy_mode** - `str` - A proxy mode to operate in. May be "DEFAULT", - "FORWARD_ONLY", or "TUNNEL_ONLY". - * **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. - * **http2** - `bool` - Enable HTTP/2 support. + Parameters + ---------- + proxy_url: + The URL of the proxy service as a 4-tuple of (scheme, host, port, path). + proxy_headers: + A list of proxy headers to include. + proxy_mode: + A proxy mode to operate in. May be "DEFAULT", "FORWARD_ONLY", or "TUNNEL_ONLY". + ssl_context: + An SSL context to use for verifying connections. + max_connections: + The maximum number of concurrent connections to allow. + max_keepalive_connections: + The maximum number of connections to allow before closing keep-alive + connections. + http2: + Enable HTTP/2 support. """ def __init__( diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 02dfed4b5..000000000 --- a/mkdocs.yml +++ /dev/null @@ -1,23 +0,0 @@ -site_name: HTTP Core -site_description: Do one thing, and do it well. -site_url: https://www.encode.io/httpcore - -theme: - name: 'material' - -repo_name: encode/httpcore -repo_url: https://github.com/encode/httpcore/ -edit_uri: "" - -nav: - - Introduction: 'index.md' - - Developer Interface: 'api.md' - - Contributing: 'contributing.md' - -markdown_extensions: - - admonition - - codehilite - - mkautodoc - -extra_css: - - css/custom.css diff --git a/requirements.txt b/requirements.txt index ea17e0a51..ddb56746e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,9 +7,13 @@ curio==1.4; python_version < '3.7' curio==1.5; python_version >= '3.7' # Docs -mkautodoc==0.1.0 -mkdocs==1.1.2 -mkdocs-material==7.1.0 +sphinx==3.5.3 +sphinx-autobuild==2021.3.14 +myst-parser==0.13.5 +furo==2021.3.20b30 +ghp-import==1.1.0 +# myst-parser + docutils==0.17 has a bug: https://github.com/executablebooks/MyST-Parser/issues/343 +docutils==0.16 # Packaging twine==3.4.1 diff --git a/scripts/build b/scripts/build index 602eab0a4..2192b90b8 100755 --- a/scripts/build +++ b/scripts/build @@ -12,4 +12,4 @@ set -x ${PREFIX}python setup.py sdist bdist_wheel ${PREFIX}twine check dist/* -${PREFIX}mkdocs build +scripts/docs build diff --git a/scripts/docs b/scripts/docs index 4ac3beb7a..b4c9f9717 100755 --- a/scripts/docs +++ b/scripts/docs @@ -1,10 +1,23 @@ -#!/bin/sh -e +#!/bin/bash -e export PREFIX="" if [ -d 'venv' ] ; then export PREFIX="venv/bin/" fi +SOURCE_DIR="docs" +OUT_DIR="build/html" + +COMMAND="$1" +ARGS="${@:2}" + set -x -${PREFIX}mkdocs serve +if [ "$COMMAND" = "build" ]; then + ${PREFIX}sphinx-build $SOURCE_DIR $OUT_DIR +elif [ "$COMMAND" = "gh-deploy" ]; then + scripts/docs build + ${PREFIX}ghp-import $OUT_DIR -np -m "Deployed $(git rev-parse --short HEAD)" $ARGS +else + ${PREFIX}sphinx-autobuild $SOURCE_DIR $OUT_DIR --watch httpcore/ $ARGS +fi diff --git a/scripts/publish b/scripts/publish index 1c4a32282..a16006d73 100755 --- a/scripts/publish +++ b/scripts/publish @@ -24,4 +24,4 @@ fi set -x ${PREFIX}twine upload dist/* -${PREFIX}mkdocs gh-deploy --force +scripts/docs gh-deploy --push