Streamline README and reorganize async documentation

[Mattsface]

Parent: #297
Depends on: #303

Goal

Make the README easier for new users to scan while documenting the new async client clearly and moving deeper reference material into dedicated docs.

The guiding documentation principle for v1.1 is:

README = landing page and quick start. Dedicated docs = reference and deeper behavior.

The README should teach a new user enough to install the package, make a sync or async request, understand the common error path, and know where to go next without forcing them through transport internals or release history first.

Why this cleanup is needed

The current README has accumulated several different responsibilities over time. It now acts as:

• project landing page
• installation guide
• quick-start guide
• HTTP transport reference
• retry/timeout reference
• compatibility-mode guide
• migration guide
• release-history summary
• public API explanation
• Pydantic/model usage guide
• endpoint/method catalog

Most of that material is useful and should be preserved, but keeping all of it inline makes the README harder to scan and creates duplication with docs/http-transport.md, docs/public-api.md, release notes, and the Wiki.

v1.1 should reorganize rather than delete useful information.

README information architecture

The README should primarily answer these questions, in roughly this order:

1. What is this package?
2. How do I install it?
3. How do I make a synchronous request?
4. How do I make an asynchronous request?
5. How do I handle the most common failures?
6. How do I work with the returned models?
7. Where is the deeper documentation?

A proposed high-level structure:

Python MLB Stats API
badges
short project description

Installation
    synchronous/default install
    async extra
    brief Python support note

Quick Start
    synchronous example
    asynchronous example

Common Error Handling
    small example
    link to HTTP transport docs

Working with Models
    one small Pydantic example

Documentation
    async usage guide
    HTTP transport
    public API contract
    endpoint/model reference / Wiki
    release notes

Contributing / Project links

License / MLB disclaimer

The exact headings may change during implementation, but the README should remain a concise entry point rather than becoming another complete reference document.

README focus

Keep the README centered on:

• short project description
• installation
• Python support at a glance
• basic synchronous usage
• basic asynchronous usage
• common error handling
• one concise model/Pydantic example
• links to deeper documentation
• contribution/project links
• required project/MLB disclaimer information

The first useful screen of the README should get users to installation and basic usage quickly. Async support should be visible near the sync quick start rather than buried below transport history.

Material that should move out of the README

Preserve this information, but move or consolidate it into the appropriate dedicated docs where practical:

• detailed HTTP status behavior
• retry-policy internals and numeric limits
• timeout semantics and advanced timeout examples
• Session/client ownership details
• custom injected Session/client examples
• exception attribute reference
• compatibility-mode details
• warning filtering guidance
• full HTTP behavior decision tables
• detailed User-Agent behavior
• public API stability rules
• advanced transport usage
• migration-specific instructions
• release-by-release transport history
• long endpoint/method catalogs already represented in the Wiki/reference material

The README may briefly summarize these features and link to their authoritative documentation, but it should not duplicate the full reference text.

Release-specific material

The README should describe the package as it exists now, not become an accumulating timeline such as:

0.8 added ...
0.9 changed ...
1.0 changed ...
1.1 added ...

Detailed upgrade guidance belongs in release notes or migration documentation.

For v1.1, prefer a short link such as:

Upgrading? See the release notes and migration guidance.

Keep historical release notes historically accurate rather than rewriting old release documents to describe current behavior.

Dedicated documentation responsibilities

The documentation should have clearer ownership boundaries.

README.md

Purpose: How do I get started?

Keep it concise and task-oriented:

• install
• sync quick start
• async quick start
• common failure example
• small model example
• documentation navigation

docs/async.md — proposed new document

Purpose: How do I use AsyncMlb correctly?

Create a dedicated async usage guide for v1.1 covering:

• installation with python-mlb-statsapi[async]
• basic sequential usage
• async with AsyncMlb() lifecycle
• explicit await mlb.aclose() when not using a context manager
• initial supported endpoint set
• unsupported/deferred endpoints where relevant
• simple concurrent usage with normal asyncio orchestration
• cancellation expectations
• caller-injected async client ownership
• timeout usage at the public API level
• short exception overview
• links to the transport reference for precise retry/error semantics

This document should not duplicate the entire HTTP transport contract.

docs/http-transport.md

Purpose: What are the precise HTTP/transport semantics?

This should remain the authoritative home for deeper behavior such as:

• timeout semantics
• retry policy
• retryable statuses
• Retry-After
• strict HTTP behavior
• 404 handling
• compatibility mode
• public transport exception mapping
• Session/client ownership rules
• cleanup behavior
• User-Agent behavior where appropriate
• sync/async transport parity where relevant

docs/public-api.md

Purpose: What public API does the project promise to keep stable?

Document the stable sync and async public surfaces, constructor signatures, result/exception contracts, and compatibility commitments here rather than expanding the README with stability-policy detail.

Wiki / endpoint reference

Purpose: What endpoints/models/methods are available and how do I use them?

Avoid maintaining a second large endpoint catalog in the README when the Wiki/reference documentation already serves that purpose.

docs/releases/

Purpose: What changed in a specific release?

Release-specific migration guidance and historical behavior belong here. Add/update v1.1 release documentation as appropriate without turning the README into a permanent release-history document.

README examples

Keep examples intentionally small.

Synchronous quick start

The README should show one or two representative calls, ideally with context-manager usage, rather than a long tour of unrelated endpoints.

Conceptually:

import mlbstatsapi

with mlbstatsapi.Mlb() as mlb:
    team = mlb.get_team(136)
    print(team.name)

Asynchronous quick start

Place the async example immediately near the sync example so users can see the relationship clearly:

import asyncio
import mlbstatsapi

async def main():
    async with mlbstatsapi.AsyncMlb() as mlb:
        team = await mlb.get_team(136)
        print(team.name)

asyncio.run(main())

Only document methods that are actually implemented and supported when #306 lands.

Common error handling

Keep one compact example in the README because users need to discover the public exception types quickly:

try:
    with mlbstatsapi.Mlb() as mlb:
        team = mlb.get_team(136)
except mlbstatsapi.MlbTimeoutError:
    ...
except mlbstatsapi.MlbHttpError as exc:
    ...

Then link to docs/http-transport.md for the complete exception, retry, timeout, compatibility, and ownership behavior.

Working with models

Keep a short Pydantic example such as model_dump() or snake_case field access, but move extended serialization examples out if they materially increase README length.

Contract documentation from #298

Dedicated async documentation must accurately describe the implemented v1.1 contract, including:

Public API and installation

• AsyncMlb and AsyncMlbDataAdapter as supported public async APIs
• installing async support through the optional async extra
• the initial supported endpoint set and any endpoints still unsupported
• existing synchronous Mlb usage remains unchanged

Lifecycle and ownership

• async with AsyncMlb() usage
• explicit await mlb.aclose()
• idempotent cleanup behavior
• library-owned vs caller-injected async clients
• caller-injected clients are not closed or silently reconfigured
• callers must finish in-flight operations before closing the client

HTTP and exceptions

Document the public behavior clearly:

2xx                         -> normal decode / parsing
404                         -> endpoint-specific empty behavior
non-404 4xx + strict=True   -> MlbHttpError
non-404 4xx + strict=False  -> MlbHttpCompatibilityWarning + empty behavior
5xx                         -> MlbHttpError
timeout                     -> MlbTimeoutError
transport failure           -> MlbTransportError
invalid successful JSON     -> MlbDecodeError
caller cancellation         -> asyncio.CancelledError

• explain that async transport-library exception types are not the public API
• keep compatibility-mode wording aligned with Document a removal timeline for strict_http=False compatibility mode #309 and the eventual documented deprecation/removal policy

Retry and timeout behavior

• same public timeout input shape/defaults as sync
• library-owned retry behavior and retryable statuses
• Retry-After behavior
• retry/backoff is asynchronous/non-blocking
• caller-injected transport configuration remains caller-controlled

Concurrency

Document the model explicitly:

• one AsyncMlb instance can support multiple concurrent in-flight requests on the same event loop
• concurrency is caller-controlled using normal asyncio orchestration
• endpoint methods do not introduce hidden fan-out/background work
• cancellation/error behavior remains independent unless caller orchestration deliberately couples tasks
• cross-thread and cross-event-loop use are not promised for v1.1

Include at least one simple concurrent usage example in docs/async.md after the basic sequential async quick start. The README itself does not need to carry the full concurrency example unless it remains concise.

User-Agent

Document only where appropriate for the transport reference:

• library-owned sync and async clients identify as python-mlb-statsapi/<installed-version>
• caller-injected clients retain caller-controlled headers

Duplication rule

When information appears in both README and dedicated docs, the README version should be a short summary that links to one authoritative source.

Avoid maintaining two full copies of:

• transport behavior
• retry values
• timeout semantics
• ownership rules
• compatibility guidance
• release-specific migration instructions

This reduces documentation drift as the library evolves.

Scope / size guidance

Do not optimize for an exact line count, but the finished README should be substantially shorter than the current version. A useful mental target is roughly one-quarter to one-third of the current size if the deeper material can be moved cleanly without losing information.

The goal is not minimal documentation; the goal is better placement of documentation.

Constraints

• preserve useful technical detail rather than deleting it
• do not document async methods that are not actually supported
• keep historical release notes historically accurate
• do not expose private transport implementation details as stable API
• documentation must match tested behavior, not planned-but-unimplemented behavior
• avoid duplicating full reference material across README and dedicated docs
• keep README examples short enough to scan while still being runnable/representative
• maintain clear links so moved material remains easy to discover

Acceptance criteria

• README reads primarily as a landing page / quick-start document
• README is substantially shorter and easier to navigate
• Installation is easy to find
• Sync quick-start remains clear
• Async installation and quick-start are easy to find
• Common public error handling remains discoverable without embedding the full transport reference
• A concise model/Pydantic example remains discoverable
• docs/async.md or an equivalent dedicated async usage guide exists
• Async endpoint support is represented accurately
• Lifecycle and caller-owned-client rules from Define the v1.1 async API and transport contract #298 are documented
• HTTP/error/compatibility decision table is documented accurately in the appropriate reference documentation
• Cancellation and concurrency behavior are documented
• Retry/timeout behavior is documented without exposing unnecessary transport internals
• Detailed transport/reference content has one clear authoritative home
• Release-specific migration/history content is moved out of the main README where practical
• Large endpoint/method catalogs are consolidated into the Wiki/reference documentation where practical
• README and dedicated docs do not maintain unnecessary full-text duplication
• Documentation examples are tested or validated where practical
• Links to moved documentation are clear and functional

Refs #297
Contract: #298
Compatibility lifecycle: #309