New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Migrate docs to Sphinx + MyST #285
Merged
Merged
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
b851862
Migrate docs to Sphinx + MyST
florimondmanca 74e43d4
Improvements
florimondmanca dc8dda8
Lint
florimondmanca a852e18
Tweak scripts/docs gh-deploy
florimondmanca 3980a9a
Fix scripts/docs cross platform support
florimondmanca 721fa36
Drop sphinx-autodoc-typehints, description mode is okay
florimondmanca ce3fca7
Merge branch 'master' into fm/docs-sphinx
florimondmanca d2dac48
Use standard bash
florimondmanca 902680a
Resolve public API source code locations
florimondmanca 115fc1d
Rename full_module -> source_module
florimondmanca d57ab7a
Merge branch 'master' into fm/docs-sphinx
florimondmanca c87f1d7
Drop unnecessary viewcode_follow_imported_members option
florimondmanca 5abe89e
Merge branch 'master' into fm/docs-sphinx
florimondmanca 7f9637d
Pin docutils==0.17
florimondmanca File filter
Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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/) | ||
<!-- Table of Content entries, shown in left sidebar. --> | ||
|
||
> *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 <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> | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Curious - what is
:noindex:
here, and why on this class in particular?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We show this class two times, once for the sync API, once for the async API. I figured it's fine, except showing them twice would make Sphinx index them twice, which raised a warning hinting to add
:noindex:
.