Docs: rewrite for 4.0, add migration guide, update CLAUDE.md

[gmr]

Summary

• Rewrite all docs for 4.0: async API, TransactionConsumer, configuration accuracy
• Delete 6 stale RST files never migrated to mkdocs
• Add comprehensive 3.x → 4.0 migration guide
• Update README with current features, extras, and TransactionConsumer example
• Update CLAUDE.md with architecture overview and corrected lint suppression notes

Test plan

• mkdocs build succeeds with no warnings
• All 208 tests pass
• Pre-commit hooks pass
• Review migration guide for completeness against 3.x API

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Async consumer framework (asyncio), TransactionConsumer for concurrent processing
  • Avro datum serialization with file/HTTP schema registries
  • YAML and TOML configuration support
  • Prometheus metrics support

• Documentation

  • Added migration guide for 3.x→4.0
  • Reworked README, consumer how‑tos, configuration, and API docs with examples and updated lifecycle/metrics guidance

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 12e037fe-7afe-48f0-9043-26b6ff289da1

📥 Commits

Reviewing files that changed from the base of the PR and between 6a7561a and db3373c.

📒 Files selected for processing (1)

• docs/consumer_howto.md

---

📝 Walkthrough

Walkthrough

This pull request comprehensively updates documentation across the rejected library to reflect version 4.0 changes, including new async consumer patterns, TransactionConsumer for concurrent processing, Avro schema registry support, YAML/TOML configuration, and an added migration guide from 3.x to 4.0. CLAUDE.md and mkdocs navigation were also updated.

Changes

Cohort / File(s)	Summary
Top-level docs & README README.md, docs/index.md, mkdocs.yml	Updated feature list and quick-start examples to emphasize asyncio-based async consumers, TransactionConsumer concurrency, Avro schema registry support, and YAML/TOML configuration; added nav entry for migrating.md.
Configuration & API docs docs/configuration.md, docs/api.md	Major restructuring of configuration docs (YAML/TOML, schema_registry, connection/consumer option tables, logging/correlation ID, Prometheus) and expanded API reference with explicit members, new models (Message, ProcessingContext, Result), exceptions namespace, testing docs, and GarbageCollectorMixin.
Consumer how‑to & examples docs/consumer_howto.md, docs/consumer.rst (removed)	Converted examples and lifecycle docs to async (async def), added TransactionConsumer with ProcessingContext and concurrent processing guidance, expanded publishing, content-type handling, custom metrics, and garbage-collector guidance; legacy consumer.rst content removed.
Migration & developer docs docs/migrating.md, CLAUDE.md	Added a comprehensive migration guide (3.x → 4.0) covering Python 3.11+, Tornado→asyncio migration, lifecycle/signature changes, module/API mapping, testing changes, and a developer-focused CLAUDE.md with architecture/process model notes.
Removed Sphinx/legacy pages docs/api_consumer.rst, docs/api_data.rst, docs/api_testing.rst, docs/cli.rst, docs/example_config.rst	Removed several legacy Sphinx-based API/CLI/config pages; content consolidated into updated Markdown docs and reorganized API reference.
Docs/testing examples & helpers docs/api_testing.rst (removed), docs/consumer_howto.md	Testing docs updated to reflect AsyncTestCase → IsolatedAsyncioTestCase, async test functions, renamed helpers (create_message → create_context), and added member-level testing docs.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Consolidate consumer classes and add Avro support #58: Documentation and migration updates matching Consumer consolidation, TransactionConsumer introduction, Avro datum support, and configuration/schema_registry changes.

Poem

🐰 Pages hopped from branch to main,
Async tunnels cleared the lane,
Schemas carried, configs spun,
From three to four we bound and run,
A carrot-map for every run! 🥕📜

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main changes: documentation rewrite for version 4.0, addition of a migration guide, and updates to CLAUDE.md.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/consumer_howto.md (1)

189-195: Document additional ProcessingContext fields for completeness.

The ProcessingContext documentation lists key fields but omits two fields shown in the code:

• result -- the Result enum indicating message disposition
• received_at -- timestamp when the message was received (useful for latency tracking)

Consider adding these to provide a complete reference.

📝 Suggested addition

 The `ProcessingContext` provides:
 
 - `ctx.message` -- the `Message` model with all AMQP properties
 - `ctx.channel` -- the pika channel for the connection
 - `ctx.connection` -- the connection object
 - `ctx.measurement` -- per-message `Measurement` for custom metrics
 - `ctx.raw_body` -- the original bytes before decoding
+- `ctx.result` -- the `Result` enum indicating message disposition (set by framework)
+- `ctx.received_at` -- timestamp when the message was received (monotonic clock)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/consumer_howto.md` around lines 189 - 195, Update the ProcessingContext
documentation to include the two missing fields shown in code: add `result` (the
Result enum indicating message disposition such as ACK/NACK/REQUEUE) and
`received_at` (timestamp when the message was received, useful for
latency/metric calculations), ensuring the descriptions mirror the existing
bullet style (e.g., `ctx.result` -- Result enum indicating message disposition;
`ctx.received_at` -- datetime/timestamp when the message was received).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/consumer_howto.md`:
- Around line 189-195: Update the ProcessingContext documentation to include the
two missing fields shown in code: add `result` (the Result enum indicating
message disposition such as ACK/NACK/REQUEUE) and `received_at` (timestamp when
the message was received, useful for latency/metric calculations), ensuring the
descriptions mirror the existing bullet style (e.g., `ctx.result` -- Result enum
indicating message disposition; `ctx.received_at` -- datetime/timestamp when the
message was received).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 26f9b51a-2872-4bff-8ac9-5d9559d6ba7f

📥 Commits

Reviewing files that changed from the base of the PR and between f581ab9 and 6a7561a.

📒 Files selected for processing (14)

• CLAUDE.md
• README.md
• docs/api.md
• docs/api_consumer.rst
• docs/api_data.rst
• docs/api_testing.rst
• docs/cli.rst
• docs/configuration.md
• docs/consumer.rst
• docs/consumer_howto.md
• docs/example_config.rst
• docs/index.md
• docs/migrating.md
• mkdocs.yml

💤 Files with no reviewable changes (6)

• docs/api_consumer.rst
• docs/api_data.rst
• docs/api_testing.rst
• docs/cli.rst
• docs/example_config.rst
• docs/consumer.rst