Skip to content

Commit b1984cc

Browse files
committed
docs: add minimal mkdocs site published via Read the Docs
1 parent a6d03f4 commit b1984cc

7 files changed

Lines changed: 114 additions & 3 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ wheels/
2323
.venv
2424
uv.lock
2525
plan.md
26+
site/

‎.readthedocs.yaml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
version: 2
2+
3+
build:
4+
os: "ubuntu-22.04"
5+
tools:
6+
python: "3.12"
7+
8+
python:
9+
install:
10+
- requirements: docs/requirements.txt
11+
12+
mkdocs:
13+
configuration: mkdocs.yml

‎docs/archive/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This directory contains the bmad-era planning artifacts for `httpware`:
88
- `product-brief-httpware.md` and `product-brief-httpware-distillate.md` — executive brief and detail pack from the predecessor `community-of-python/base-client` scoping exercise.
99
- `stories/` — per-story specs (1-1 through 1-5) and the retired `sprint-status.yaml`.
1010

11-
These files are **historical reference, not authoritative**. The load-bearing decisions were distilled into [`../engineering.md`](../engineering.md) on 2026-05-31 when the project switched workflows from bmad to superpowers. Consult these archived files only when you need:
11+
These files are **historical reference, not authoritative**. The load-bearing decisions were distilled into [`../dev/engineering.md`](../dev/engineering.md) on 2026-05-31 when the project switched workflows from bmad to superpowers. Consult these archived files only when you need:
1212

1313
- Original rationale behind a decision (e.g., "why did we choose `httpx2` over `aiohttp`?").
1414
- The specific FR/NFR numbers that a future spec wants to cite (e.g., `archive/prd.md#NFR-12`).

‎docs/dev/engineering.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# `httpware` engineering notes
22

3-
This doc is the single distilled reference for `httpware` design rationale, protocol seams, and remaining roadmap. It complements [`../CLAUDE.md`](../CLAUDE.md): `CLAUDE.md` holds AI-enforced invariants and operational commands; this file holds the reasoning and the structural map.
3+
This doc is the single distilled reference for `httpware` design rationale, protocol seams, and remaining roadmap. It complements `CLAUDE.md` (at the repo root): `CLAUDE.md` holds AI-enforced invariants and operational commands; this file holds the reasoning and the structural map.
44

55
## 1. Project intent
66

@@ -182,4 +182,4 @@ When work starts on a roadmap item, it gets a spec at `planning/specs/YYYY-MM-DD
182182

183183
## 9. Deferred work
184184

185-
Review-surfaced items that are real but not actionable now live in [`./deferred-work.md`](./deferred-work.md). Each entry cites the originating story and the file/line, and explains why the fix is deferred (cross-story dependency, scope, performance/security tradeoff, etc.). When a deferred item becomes actionable, it migrates into the spec for the story that resolves it.
185+
Review-surfaced items that are real but not actionable now live in `docs/deferred-work.md` (in the repository). Each entry cites the originating story and the file/line, and explains why the fix is deferred (cross-story dependency, scope, performance/security tradeoff, etc.). When a deferred item becomes actionable, it migrates into the spec for the story that resolves it.

‎docs/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# httpware
2+
3+
A Python async HTTP client framework for building resilient service clients. `httpware` owns the abstraction layer above the underlying HTTP client (`httpx2` by default); consumers never import the transport directly.
4+
5+
> **Status:** Pre-1.0 (0.1.0 alpha). Public API is subject to change between minor releases until v1.0.
6+
7+
## Install
8+
9+
```bash
10+
pip install httpware
11+
```
12+
13+
Optional extras:
14+
15+
```bash
16+
pip install httpware[msgspec] # MsgspecDecoder
17+
```
18+
19+
## First request
20+
21+
```python
22+
import asyncio
23+
24+
from httpware import AsyncClient
25+
from pydantic import BaseModel
26+
27+
28+
class User(BaseModel):
29+
id: int
30+
name: str
31+
32+
33+
async def main() -> None:
34+
async with AsyncClient(base_url="https://api.example.com") as client:
35+
user = await client.get("/users/1", response_model=User)
36+
print(user.name)
37+
38+
39+
asyncio.run(main())
40+
```
41+
42+
## Where to go next
43+
44+
- **[Engineering Notes](dev/engineering.md)** — design invariants, the five protocol seams, exception contract, module layout, testing patterns, optional-extras pattern.
45+
- **[Contributing](dev/contributing.md)** — setup, conventions, workflow.
46+
47+
## Part of `modern-python`
48+
49+
`httpware` ships under the [`modern-python`](https://github.com/modern-python) org. See the org profile for the categorized index of related templates and libraries.

‎docs/requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
mkdocs
2+
mkdocs-material

‎mkdocs.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
site_name: httpware
2+
site_url: https://httpware.readthedocs.io/
3+
repo_url: https://github.com/modern-python/httpware
4+
docs_dir: docs
5+
edit_uri: edit/main/docs/
6+
7+
nav:
8+
- Quick-Start: index.md
9+
- Development:
10+
- Engineering Notes: dev/engineering.md
11+
- Contributing: dev/contributing.md
12+
13+
theme:
14+
name: material
15+
features:
16+
- content.code.copy
17+
- content.action.edit
18+
- navigation.footer
19+
- navigation.sections
20+
- navigation.top
21+
- header.autohide
22+
palette:
23+
- media: "(prefers-color-scheme: light)"
24+
scheme: default
25+
primary: black
26+
accent: pink
27+
toggle:
28+
icon: material/brightness-7
29+
name: Switch to dark mode
30+
- media: "(prefers-color-scheme: dark)"
31+
scheme: slate
32+
primary: black
33+
accent: pink
34+
toggle:
35+
icon: material/brightness-4
36+
name: Switch to system preference
37+
38+
markdown_extensions:
39+
- toc:
40+
permalink: true
41+
- pymdownx.highlight:
42+
anchor_linenums: true
43+
- pymdownx.inlinehilite
44+
- pymdownx.superfences
45+
- admonition
46+
- attr_list

0 commit comments

Comments
 (0)