Vishesh 'ironeagle' Bangotra
370d1272bf
- Add hand-written wiki (index, overview, how-to, extending, dev) following the platform anatomy - Remove stale nested docs/lib/mail_intake and regenerate the flat lib reference to match docforge.nav.yml - Regenerate MCP bundle with standardized docstrings
88 lines
1.9 KiB
Markdown
88 lines
1.9 KiB
Markdown
# 🛠️ Development
|
|
|
|
Working on `mail-intake` itself.
|
|
|
|
---
|
|
|
|
## 📂 Repository layout
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `mail_intake/` | The library package (adapters, auth, credentials, parsers, ingestion, models) |
|
|
| `mail_intake/*.pyi` | Type stubs kept in sync with implementations |
|
|
| `tests/` | Unit and integration tests (mock transports, no live mail) |
|
|
| `docs/lib/` | Generated library reference (docforge, flat layout) |
|
|
| `docs/mcp/` | Machine-readable bundle served by the MCP server |
|
|
| `docs/wiki/` | This hand-written wiki |
|
|
|
|
---
|
|
|
|
## 🔧 Setup
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
.venv/Scripts/pip install -e ".[dev]"
|
|
```
|
|
|
|
> OAuth credential files (`credentials*.json`, `token.pickle`,
|
|
> `client_secret_*.json`) are gitignored — keep them out of the repository.
|
|
|
|
---
|
|
|
|
## 🧪 Tests
|
|
|
|
Run the suite (no network or live Gmail required):
|
|
|
|
```bash
|
|
.venv/Scripts/pytest
|
|
```
|
|
|
|
Coverage spans ingestion flows, credential stores, parsers, and auth against
|
|
mock providers.
|
|
|
|
---
|
|
|
|
## ✅ Quality gates
|
|
|
|
The CI quality gate runs, matching the Drone pipeline:
|
|
|
|
```bash
|
|
.venv/Scripts/black --check .
|
|
.venv/Scripts/ruff check .
|
|
.venv/Scripts/mypy
|
|
.venv/Scripts/pytest
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Building documentation (docforge)
|
|
|
|
The site is generated by [`docforge`](https://git.aetoskia.com/aetos/doc-forge)
|
|
and served per kind under `site/{kind}`:
|
|
|
|
```bash
|
|
doc-forge build \
|
|
--mkdocs --mcp --wiki \
|
|
--module-is-source --module mail_intake \
|
|
--site-name "Mail Intake"
|
|
```
|
|
|
|
- `--module-is-source` renders the flat `docs/lib/` layout (no nesting under
|
|
`mail_intake/`), matching `docforge.nav.yml` and `docs/mkdocs.lib.yml`.
|
|
- `--mcp` regenerates the structured bundle in `docs/mcp/`.
|
|
- `--wiki` builds this wiki.
|
|
|
|
Preview locally:
|
|
|
|
```bash
|
|
doc-forge serve --lib
|
|
doc-forge serve --wiki
|
|
doc-forge serve --mcp
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Read Next
|
|
|
|
- [Extending Mail Intake](03_extending.md) — custom adapters and stores.
|
|
- [Overview](01_overview.md) — the core architecture. |