Skip to content

Commit 34554d0

Browse files
MattsfaceMattsface
authored
docs: publish documentation site (#336)
Publish the project documentation with MkDocs and GitHub Pages, and route README documentation links to the rendered site.
1 parent 9a663e5 commit 34554d0

7 files changed

Lines changed: 269 additions & 17 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
name: Documentation
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
paths:
8+
- ".github/workflows/docs.yml"
9+
- "docs/**"
10+
- "mkdocs.yml"
11+
- "requirements-docs.txt"
12+
push:
13+
branches:
14+
- main
15+
paths:
16+
- ".github/workflows/docs.yml"
17+
- "docs/**"
18+
- "mkdocs.yml"
19+
- "requirements-docs.txt"
20+
workflow_dispatch:
21+
22+
permissions:
23+
contents: read
24+
pages: write
25+
id-token: write
26+
27+
concurrency:
28+
group: pages-${{ github.ref }}
29+
cancel-in-progress: false
30+
31+
jobs:
32+
build:
33+
name: Build documentation
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- name: Check out repository
38+
uses: actions/checkout@v7
39+
40+
- name: Set up Python
41+
uses: actions/setup-python@v7
42+
with:
43+
python-version: "3.14"
44+
cache: pip
45+
cache-dependency-path: requirements-docs.txt
46+
47+
- name: Install documentation dependencies
48+
run: python -m pip install --requirement requirements-docs.txt
49+
50+
- name: Configure GitHub Pages
51+
if: github.ref == 'refs/heads/main'
52+
uses: actions/configure-pages@v6
53+
54+
- name: Build documentation
55+
run: mkdocs build --strict --site-dir site
56+
57+
- name: Upload GitHub Pages artifact
58+
if: github.ref == 'refs/heads/main'
59+
uses: actions/upload-pages-artifact@v5
60+
with:
61+
path: site
62+
63+
deploy:
64+
name: Deploy documentation
65+
if: github.ref == 'refs/heads/main'
66+
needs: build
67+
runs-on: ubuntu-latest
68+
environment:
69+
name: github-pages
70+
url: ${{ steps.deployment.outputs.page_url }}
71+
72+
steps:
73+
- name: Deploy to GitHub Pages
74+
id: deployment
75+
uses: actions/deploy-pages@v5

‎README.md‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-mlb-statsapi)
1010
![GitHub](https://img.shields.io/github/license/zero-sum-seattle/python-mlb-statsapi)
1111

12-
### [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/)
12+
### [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/)
1313

1414
</div>
1515

@@ -46,7 +46,7 @@ The async extra installs HTTPX. Python 3.10 or newer is required.
4646
| Minimum Python version | `>=3.10` |
4747
| CI-validated versions | Python 3.10 through 3.14 (`3.10`, `3.11`, `3.12`, `3.13`, `3.14`) |
4848

49-
See [Python support](docs/public-api.md#python-support) for the complete policy.
49+
See [Python support](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/#python-support) for the complete policy.
5050

5151
## Quick Start
5252

@@ -126,7 +126,7 @@ async def main():
126126
asyncio.run(main())
127127
```
128128

129-
See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX clients, and the current async endpoint list.
129+
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.
130130

131131
## Sync or Async?
132132

@@ -139,7 +139,7 @@ See [Async usage](docs/async.md) for lifecycle, concurrency, custom HTTPX client
139139

140140
`AsyncMlb` mirrors the full endpoint surface of `Mlb`. Both clients return the same Pydantic models and follow the same public HTTP/error behavior.
141141

142-
See the [public API contract](docs/public-api.md#asyncmlb-public-client) for the authoritative method list and signatures.
142+
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.
143143

144144
## Concurrent Async Requests
145145

@@ -188,21 +188,21 @@ team_ids = mlb.get_team_id("Seattle Mariners")
188188

189189
### Stats
190190

191-
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`.
191+
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`.
192192

193193
### Schedule
194194

195195
```python
196196
schedule = mlb.get_schedule(date="2022-10-13")
197197
```
198198

199-
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).
199+
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/).
200200

201201
## HTTP and Error Behavior
202202

203203
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.
204204

205-
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.
205+
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.
206206

207207
The main transport exceptions are:
208208

@@ -223,7 +223,7 @@ except MlbHttpError as exc:
223223
print(exc.status_code, exc.reason)
224224
```
225225

226-
For timeouts, retries, compatibility mode, ownership rules, and transport details, see [docs/http-transport.md](docs/http-transport.md).
226+
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/).
227227

228228
## Working with Models
229229

@@ -244,14 +244,14 @@ print(player.model_dump_json(indent=2))
244244

245245
| Document | Contents |
246246
| --- | --- |
247-
| [Wiki](https://github.com/zero-sum-seattle/python-mlb-statsapi/wiki) | Endpoint reference, return objects, and model documentation |
248-
| [Method reference](docs/methods.md) | Method signatures and short descriptions from the original README reference |
249-
| [Usage examples](docs/examples.md) | Extended synchronous examples |
250-
| [Stats guide](docs/stats.md) | Player, team, general, and per-game stat queries with sync and async examples |
251-
| [Async usage](docs/async.md) | Async installation, lifecycle, concurrency, and examples |
252-
| [HTTP transport](docs/http-transport.md) | Timeouts, retries, strict HTTP, exceptions, and ownership |
253-
| [Public API contract](docs/public-api.md) | Supported symbols, signatures, endpoint methods, and stability policy |
254-
| [Release notes](docs/releases/) | Release-specific changes and migration notes |
247+
| [Documentation home](https://zero-sum-seattle.github.io/python-mlb-statsapi/) | Installation, quick starts, and links to every guide |
248+
| [Method reference](https://zero-sum-seattle.github.io/python-mlb-statsapi/methods/) | Method signatures and short descriptions from the original README reference |
249+
| [Usage examples](https://zero-sum-seattle.github.io/python-mlb-statsapi/examples/) | Extended synchronous examples |
250+
| [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 |
251+
| [Async usage](https://zero-sum-seattle.github.io/python-mlb-statsapi/async/) | Async installation, lifecycle, concurrency, and examples |
252+
| [HTTP transport](https://zero-sum-seattle.github.io/python-mlb-statsapi/http-transport/) | Timeouts, retries, strict HTTP, exceptions, and ownership |
253+
| [Public API contract](https://zero-sum-seattle.github.io/python-mlb-statsapi/public-api/) | Supported symbols, signatures, endpoint methods, and stability policy |
254+
| [Release notes](https://zero-sum-seattle.github.io/python-mlb-statsapi/releases/) | Release-specific changes and migration notes |
255255

256256
## Contributing
257257

‎docs/async.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -225,7 +225,7 @@ behavior.
225225

226226
## Documentation boundaries
227227

228-
- [README](../README.md) — installation and quick-start examples
228+
- [Documentation home](index.md) — installation and quick-start examples
229229
- [Usage examples](examples.md) — longer synchronous examples
230230
- [Public API contract](public-api.md) — supported symbols, signatures, and endpoint coverage
231231
- [HTTP transport](http-transport.md) — timeouts, retries, errors, and compatibility behavior

‎docs/index.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Python MLB Stats API
2+
3+
`python-mlb-statsapi` is a Python client for MLB's Stats API with synchronous and asynchronous interfaces.
4+
5+
[View usage examples](examples.md){ .md-button .md-button--primary }
6+
[Browse the method reference](methods.md){ .md-button }
7+
8+
<div class="grid cards" markdown>
9+
10+
- **Broad API coverage**
11+
12+
Query teams, players, schedules, games, statistics, and more.
13+
14+
- **Pythonic models**
15+
16+
Work with [Pydantic](https://docs.pydantic.dev/) objects whose fields use `snake_case` names.
17+
18+
- **Sync and async**
19+
20+
Choose the synchronous `Mlb` client or the asynchronous `AsyncMlb` client. Existing sync users can upgrade without changing their code.
21+
22+
</div>
23+
24+
## Installation
25+
26+
Install the synchronous client:
27+
28+
```bash
29+
python3 -m pip install python-mlb-statsapi
30+
```
31+
32+
Install the optional `async` extra to use `AsyncMlb` and `AsyncMlbDataAdapter`:
33+
34+
```bash
35+
python3 -m pip install "python-mlb-statsapi[async]"
36+
```
37+
38+
Python 3.10 or newer is required.
39+
40+
## Quick start
41+
42+
### Synchronous client
43+
44+
```python
45+
from mlbstatsapi import Mlb
46+
47+
with Mlb() as mlb:
48+
player = mlb.get_person(664034)
49+
team = mlb.get_team(136)
50+
51+
print(player.full_name)
52+
print(team.name)
53+
```
54+
55+
### Asynchronous client
56+
57+
```python
58+
import asyncio
59+
60+
from mlbstatsapi import AsyncMlb
61+
62+
63+
async def main():
64+
async with AsyncMlb() as mlb:
65+
player = await mlb.get_person(664034)
66+
team = await mlb.get_team(136)
67+
68+
print(player.full_name)
69+
print(team.name)
70+
71+
72+
asyncio.run(main())
73+
```
74+
75+
## Explore the documentation
76+
77+
- [Usage examples](examples.md) cover common synchronous workflows.
78+
- [Stats guide](stats.md) explains player, team, general, and per-game statistics.
79+
- [Async usage](async.md) covers lifecycle, concurrency, custom HTTPX clients, and endpoint support.
80+
- [Method reference](methods.md) lists the available endpoint methods.
81+
- [HTTP transport](http-transport.md) documents timeouts, retries, errors, proxies, and ownership.
82+
- [Public API contract](public-api.md) defines supported symbols and compatibility guarantees.
83+
- [Release notes](releases.md) summarize each published version.
84+
85+
> **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.

‎docs/releases.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Release Notes
2+
3+
Release notes describe user-visible changes, compatibility guidance, and validation performed for each published version.
4+
5+
## Releases
6+
7+
- [1.1.0](releases/1.1.0.md) — first-class asynchronous client support
8+
- [1.0.1](releases/1.0.1.md) — packaging and Python support corrections
9+
- [1.0.0](releases/1.0.0.md) — strict HTTP behavior by default and a stable public API contract
10+
- [0.9.0](releases/0.9.0.md) — public retry policy, richer HTTP errors, and compatibility warnings
11+
- [0.8.0](releases/0.8.0.md) — shared sessions, explicit timeouts, retries, and structured exceptions
12+
- [0.7.1](releases/0.7.1.md) — Pydantic v2 migration and Pythonic model fields
13+

‎mkdocs.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
site_name: Python MLB Stats API
2+
site_description: Unofficial Python client for MLB's Stats API with synchronous and asynchronous interfaces.
3+
site_url: https://zero-sum-seattle.github.io/python-mlb-statsapi/
4+
repo_url: https://github.com/zero-sum-seattle/python-mlb-statsapi
5+
repo_name: zero-sum-seattle/python-mlb-statsapi
6+
edit_uri: edit/main/docs/
7+
copyright: Unofficial project. Not affiliated with Major League Baseball or any MLB team.
8+
9+
theme:
10+
name: material
11+
language: en
12+
features:
13+
- content.action.edit
14+
- content.action.view
15+
- content.code.copy
16+
- navigation.footer
17+
- navigation.instant
18+
- navigation.sections
19+
- navigation.top
20+
- search.highlight
21+
- search.share
22+
palette:
23+
- media: "(prefers-color-scheme: light)"
24+
scheme: default
25+
primary: indigo
26+
accent: red
27+
toggle:
28+
icon: material/brightness-7
29+
name: Switch to dark mode
30+
- media: "(prefers-color-scheme: dark)"
31+
scheme: slate
32+
primary: indigo
33+
accent: red
34+
toggle:
35+
icon: material/brightness-4
36+
name: Switch to light mode
37+
38+
nav:
39+
- Home: index.md
40+
- Guides:
41+
- Usage Examples: examples.md
42+
- Stats Guide: stats.md
43+
- Async Usage: async.md
44+
- Reference:
45+
- Method Reference: methods.md
46+
- HTTP Transport: http-transport.md
47+
- Public API Contract: public-api.md
48+
- Release Notes:
49+
- Overview: releases.md
50+
- 1.1.0: releases/1.1.0.md
51+
- 1.0.1: releases/1.0.1.md
52+
- 1.0.0: releases/1.0.0.md
53+
- 0.9.0: releases/0.9.0.md
54+
- 0.8.0: releases/0.8.0.md
55+
- 0.7.1: releases/0.7.1.md
56+
57+
plugins:
58+
- search
59+
60+
markdown_extensions:
61+
- admonition
62+
- attr_list
63+
- md_in_html
64+
- tables
65+
- toc:
66+
permalink: true
67+
- pymdownx.highlight:
68+
anchor_linenums: true
69+
- pymdownx.inlinehilite
70+
- pymdownx.superfences
71+
72+
validation:
73+
omitted_files: warn
74+
absolute_links: warn
75+
unrecognized_links: warn
76+
anchors: warn

‎requirements-docs.txt‎

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

0 commit comments

Comments
 (0)