diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..73ea66f5 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,75 @@ +name: Documentation + +on: + pull_request: + branches: + - main + paths: + - ".github/workflows/docs.yml" + - "docs/**" + - "mkdocs.yml" + - "requirements-docs.txt" + push: + branches: + - main + paths: + - ".github/workflows/docs.yml" + - "docs/**" + - "mkdocs.yml" + - "requirements-docs.txt" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: false + +jobs: + build: + name: Build documentation + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v7 + + - name: Set up Python + uses: actions/setup-python@v7 + with: + python-version: "3.14" + cache: pip + cache-dependency-path: requirements-docs.txt + + - name: Install documentation dependencies + run: python -m pip install --requirement requirements-docs.txt + + - name: Configure GitHub Pages + if: github.ref == 'refs/heads/main' + uses: actions/configure-pages@v6 + + - name: Build documentation + run: mkdocs build --strict --site-dir site + + - name: Upload GitHub Pages artifact + if: github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v5 + with: + path: site + + deploy: + name: Deploy documentation + if: github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v5 diff --git a/README.md b/README.md index 7baac003..8f4ded7c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-mlb-statsapi) ![GitHub](https://img.shields.io/github/license/zero-sum-seattle/python-mlb-statsapi) -### [Wiki](https://github.com/zero-sum-seattle/python-mlb-statsapi/wiki) | [Methods](docs/methods.md) | [Examples](docs/examples.md) | [Stats](docs/stats.md) | [Async](docs/async.md) | [Public API](docs/public-api.md) | [MLB Stats API](https://statsapi.mlb.com/) +### [Docs](https://zero-sum-seattle.github.io/python-mlb-statsapi/) | [Methods](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) | [Examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/) | [Stats](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) | [Async](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) | [Public API](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/) | [MLB Stats API](https://statsapi.mlb.com/) @@ -46,7 +46,7 @@ The async extra installs HTTPX. Python 3.10 or newer is required. | Minimum Python version | `>=3.10` | | CI-validated versions | Python 3.10 through 3.14 (`3.10`, `3.11`, `3.12`, `3.13`, `3.14`) | -See [Python support](docs/public-api.md#python-support) for the complete policy. +See [Python support](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/#python-support) for the complete policy. ## Quick Start @@ -126,7 +126,7 @@ async def main(): asyncio.run(main()) ``` -See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list. +See [Async usage](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list. ## Sync or Async? @@ -139,7 +139,7 @@ See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX client `AsyncMlb` mirrors the full endpoint surface of `Mlb`. Both clients return the same Pydantic models and follow the same public HTTP/error behavior. -See the [public API contract](docs/public-api.md#asyncmlb-public-client) for the authoritative method list and signatures. +See the [public API contract](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/#asyncmlb-public-client) for the authoritative method list and signatures. ## Concurrent Async Requests @@ -188,7 +188,7 @@ team_ids = mlb.get_team_id("Seattle Mariners") ### Stats -The stats API has several entry points and returns a nested `stats[group][type]` structure. See the dedicated [Stats Guide](docs/stats.md) for `get_player_stats()`, `get_team_stats()`, `get_stats()`, and `get_players_stats_for_game()` examples using both `Mlb` and `AsyncMlb`. +The stats API has several entry points and returns a nested `stats[group][type]` structure. See the dedicated [Stats Guide](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) for `get_player_stats()`, `get_team_stats()`, `get_stats()`, and `get_players_stats_for_game()` examples using both `Mlb` and `AsyncMlb`. ### Schedule @@ -196,13 +196,13 @@ The stats API has several entry points and returns a nested `stats[group][type]` schedule = mlb.get_schedule(date="2022-10-13") ``` -See the [method reference](docs/methods.md) for the full method documentation that previously lived in the README. Longer runnable examples live in [docs/examples.md](docs/examples.md). +See the [method reference](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) for the full method documentation that previously lived in the README. Longer runnable examples live in the [usage examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/). ## HTTP and Error Behavior Both clients use explicit timeouts, structured exceptions, and pooled HTTP connections. `strict_http=True` is the default. Final non-404 4xx responses raise `MlbHttpError`, while existing endpoint-specific 404 behavior is preserved. -Library-created clients send a versioned User-Agent. The current package version sends `python-mlb-statsapi/1.1.0`. See the [HTTP transport documentation](docs/http-transport.md) for the full transport contract. +Library-created clients send a versioned User-Agent. The current package version sends `python-mlb-statsapi/1.1.0`. See the [HTTP transport documentation](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/) for the full transport contract. The main transport exceptions are: @@ -223,7 +223,7 @@ except MlbHttpError as exc: print(exc.status_code, exc.reason) ``` -For timeouts, retries, compatibility mode, ownership rules, and transport details, see [docs/http-transport.md](docs/http-transport.md). +For timeouts, retries, compatibility mode, ownership rules, and transport details, see the [HTTP transport documentation](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/). ## Working with Models @@ -244,14 +244,14 @@ print(player.model_dump_json(indent=2)) | Document | Contents | | --- | --- | -| [Wiki](https://github.com/zero-sum-seattle/python-mlb-statsapi/wiki) | Endpoint reference, return objects, and model documentation | -| [Method reference](docs/methods.md) | Method signatures and short descriptions from the original README reference | -| [Usage examples](docs/examples.md) | Extended synchronous examples | -| [Stats guide](docs/stats.md) | Player, team, general, and per-game stat queries with sync and async examples | -| [Async usage](docs/async.md) | Async installation, lifecycle, concurrency, and examples | -| [HTTP transport](docs/http-transport.md) | Timeouts, retries, strict HTTP, exceptions, and ownership | -| [Public API contract](docs/public-api.md) | Supported symbols, signatures, endpoint methods, and stability policy | -| [Release notes](docs/releases/) | Release-specific changes and migration notes | +| [Documentation home](https://zero-sum-seattle.github.io/python-mlb-statsapi/) | Installation, quick starts, and links to every guide | +| [Method reference](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) | Method signatures and short descriptions from the original README reference | +| [Usage examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/) | Extended synchronous examples | +| [Stats guide](https://zero-sum-seattle.github.io/python-mlb-statsapi/stats/) | Player, team, general, and per-game stat queries with sync and async examples | +| [Async usage](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) | Async installation, lifecycle, concurrency, and examples | +| [HTTP transport](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/) | Timeouts, retries, strict HTTP, exceptions, and ownership | +| [Public API contract](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/) | Supported symbols, signatures, endpoint methods, and stability policy | +| [Release notes](https://zero-sum-seattle.github.io/python-mlb-statsapi/releases/) | Release-specific changes and migration notes | ## Contributing diff --git a/docs/async.md b/docs/async.md index 0103a069..ad1d927c 100644 --- a/docs/async.md +++ b/docs/async.md @@ -225,7 +225,7 @@ behavior. ## Documentation boundaries -- [README](../README.md) — installation and quick-start examples +- [Documentation home](index.md) — installation and quick-start examples - [Usage examples](examples.md) — longer synchronous examples - [Public API contract](public-api.md) — supported symbols, signatures, and endpoint coverage - [HTTP transport](http-transport.md) — timeouts, retries, errors, and compatibility behavior diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4c4b295d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,85 @@ +# Python MLB Stats API + +`python-mlb-statsapi` is a Python client for MLB's Stats API with synchronous and asynchronous interfaces. + +[View usage examples](examples.md){ .md-button .md-button--primary } +[Browse the method reference](methods.md){ .md-button } + +
+ +- **Broad API coverage** + + Query teams, players, schedules, games, statistics, and more. + +- **Pythonic models** + + Work with [Pydantic](https://docs.pydantic.dev/) objects whose fields use `snake_case` names. + +- **Sync and async** + + Choose the synchronous `Mlb` client or the asynchronous `AsyncMlb` client. Existing sync users can upgrade without changing their code. + +
+ +## Installation + +Install the synchronous client: + +```bash +python3 -m pip install python-mlb-statsapi +``` + +Install the optional `async` extra to use `AsyncMlb` and `AsyncMlbDataAdapter`: + +```bash +python3 -m pip install "python-mlb-statsapi[async]" +``` + +Python 3.10 or newer is required. + +## Quick start + +### Synchronous client + +```python +from mlbstatsapi import Mlb + +with Mlb() as mlb: + player = mlb.get_person(664034) + team = mlb.get_team(136) + +print(player.full_name) +print(team.name) +``` + +### Asynchronous client + +```python +import asyncio + +from mlbstatsapi import AsyncMlb + + +async def main(): + async with AsyncMlb() as mlb: + player = await mlb.get_person(664034) + team = await mlb.get_team(136) + + print(player.full_name) + print(team.name) + + +asyncio.run(main()) +``` + +## Explore the documentation + +- [Usage examples](examples.md) cover common synchronous workflows. +- [Stats guide](stats.md) explains player, team, general, and per-game statistics. +- [Async usage](async.md) covers lifecycle, concurrency, custom HTTPX clients, and endpoint support. +- [Method reference](methods.md) lists the available endpoint methods. +- [HTTP transport](http-transport.md) documents timeouts, retries, errors, proxies, and ownership. +- [Public API contract](public-api.md) defines supported symbols and compatibility guarantees. +- [Release notes](releases.md) summarize each published version. + +> **Unofficial project.** This package and its authors are not affiliated with or endorsed by Major League Baseball or any MLB team. Use of MLB data is subject to [MLB's copyright notice](https://gdx.mlb.com/components/copyright.txt). This is an educational project—not for commercial use. diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 00000000..5ce7bb62 --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,13 @@ +# Release Notes + +Release notes describe user-visible changes, compatibility guidance, and validation performed for each published version. + +## Releases + +- [1.1.0](releases/1.1.0.md) — first-class asynchronous client support +- [1.0.1](releases/1.0.1.md) — packaging and Python support corrections +- [1.0.0](releases/1.0.0.md) — strict HTTP behavior by default and a stable public API contract +- [0.9.0](releases/0.9.0.md) — public retry policy, richer HTTP errors, and compatibility warnings +- [0.8.0](releases/0.8.0.md) — shared sessions, explicit timeouts, retries, and structured exceptions +- [0.7.1](releases/0.7.1.md) — Pydantic v2 migration and Pythonic model fields + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..1d4010ce --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,76 @@ +site_name: Python MLB Stats API +site_description: Unofficial Python client for MLB's Stats API with synchronous and asynchronous interfaces. +site_url: https://zero-sum-seattle.github.io/python-mlb-statsapi/ +repo_url: https://github.com/zero-sum-seattle/python-mlb-statsapi +repo_name: zero-sum-seattle/python-mlb-statsapi +edit_uri: edit/main/docs/ +copyright: Unofficial project. Not affiliated with Major League Baseball or any MLB team. + +theme: + name: material + language: en + features: + - content.action.edit + - content.action.view + - content.code.copy + - navigation.footer + - navigation.instant + - navigation.sections + - navigation.top + - search.highlight + - search.share + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: red + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: red + toggle: + icon: material/brightness-4 + name: Switch to light mode + +nav: + - Home: index.md + - Guides: + - Usage Examples: examples.md + - Stats Guide: stats.md + - Async Usage: async.md + - Reference: + - Method Reference: methods.md + - HTTP Transport: http-transport.md + - Public API Contract: public-api.md + - Release Notes: + - Overview: releases.md + - 1.1.0: releases/1.1.0.md + - 1.0.1: releases/1.0.1.md + - 1.0.0: releases/1.0.0.md + - 0.9.0: releases/0.9.0.md + - 0.8.0: releases/0.8.0.md + - 0.7.1: releases/0.7.1.md + +plugins: + - search + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - tables + - toc: + permalink: true + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.superfences + +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + anchors: warn diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..c2c982cf --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +mkdocs==1.6.1 +mkdocs-material==9.7.7 +