docs: add pdoc API documentation + audit docstrings (#216)

[Olen]

Summary

Closes #216.

Adds an API documentation generator (pdoc) and the supporting CI to publish it to GitHub Pages on every push to main. Also a focused audit of the public-API docstrings, since pdoc renders them verbatim — any inaccuracies become user-visible the moment we publish.

Attribution / history

The original suggestion and choice of pdoc come from @elliot-100's branch `feat/auto-doc` — but that branch was forked from main back in February 2026 and never rebased. As of today its diff against main would silently revert:

• the `/auth2/login` migration (fix: update login to /auth2/login endpoint #230, shipped in v1.2.1),
• the `meetupTimestamp` fix in `examples/ical.py` (feat(ical): use meetupTimestamp as event start when available #228),
• the auto-update-prs workflow (ci: opt-in auto-update of PRs labeled 'updateme' #231),
• multiple action-version bumps (`actions/checkout` v4→v6, `actions/setup-python` v5→v6, `softprops/action-gh-release` v2→v3),
• the README sections about `get_posts()`, `get_profile()`, contributor workflow, and `manual_test_functions.py`,
• the `TestLogin` test class.

So I rescued the idea onto a fresh branch from current main rather than try to rebase. The actual content the branch contributed was tiny (pdoc dev dep + a 6-line README hint); the bulk of this PR is the docstring audit and CI workflow.

What's in this PR

1. Tooling (`pyproject.toml`)

• Add `pdoc = ">=16.0.0"` to dev dependencies.

2. Where docs live and what they look like

Hosted (after merge): https://olen.github.io/Spond/ — automatically rebuilt on every push to `main` by the new workflow. URL hierarchy:

• `/` → top-level package index (lists the `spond` submodule)
• `/spond.html` → `spond` package page (shows the new module-level docstring + `JSONDict`, `AuthenticationError`)
• `/spond/spond.html` → `spond.spond` module (the main `Spond` class + all public methods)
• `/spond/club.html` → `spond.club` module (`SpondClub` + `get_transactions`)
• `/spond/base.html` → `spond.base` module (`_SpondBase` private but its public members surface here)

Look and feel — pdoc renders a left-nav of all public symbols (private `_`-prefixed names are auto-hidden from nav but their source is still accessible), each function/class gets its docstring rendered as Markdown plus a "View Source" link inline with the signature. Search index is built into a JS-based filter box at the top.

Locally: `poetry run pdoc ./spond` opens `http://localhost:8080\` with the same view, but live-reloads on docstring edits — useful when iterating.

3. CI workflow (`.github/workflows/publish-docs.yml`)

• Triggers on `push` to `main` and on `workflow_dispatch` (manual rebuild).
• Uses the modern artifact-based Pages deployment: `actions/configure-pages` + `actions/upload-pages-artifact` + `actions/deploy-pages`. No `gh-pages` branch, no commits pushed back to main, deploys are atomic.
• Concurrency: serialized on the `pages` group with `cancel-in-progress: false` so a fast follow-up push doesn't race a mid-flight deploy and leave Pages partially uploaded.
• Both jobs gated on `github.repository_owner == 'Olen'` so forks don't fail trying to deploy to Pages they don't control.

⚙️ One-time settings step required

Before the deploy will succeed, GitHub Pages needs to be enabled at Settings → Pages → Source = "GitHub Actions". This is a one-time toggle per repo and not configurable via the workflow file. Until that's flipped, the `Build` job will succeed but `Deploy` will fail at `actions/configure-pages`. After flipping, just re-run the workflow once via the Actions tab.

4. Docstring audit

pdoc-driven pass over the public API. Fixed:

File	Symbol	Issue
`init.py`	(module)	No module-level docstring → pdoc landing page was empty. Added one.
`base.py`	`auth_headers`	Property had no docstring despite being part of the inherited public surface.
`base.py`	`require_authentication`	Decorator was undocumented.
`base.py`	`login()`	Public method, no docstring. Now documents it, the `AuthenticationError` it raises, and that `require_authentication` calls it implicitly.
`spond.py`	`get_events`	Docstring said `GroupId` (uppercase) but the actual API param is `groupId` (line 384). Stray `(TO DO: probably events for which invites haven't been sent yet?)` removed and replaced with a concrete description of scheduled events. Parameter block reordered so `max_end, min_end, max_start, min_start` matches the function signature instead of `max_end, max_start, min_end, min_start`.
`club.py`	`get_transactions`	Docstring parameter order was `club_id, max_items, skip` but the signature is `club_id, skip, max_items` — reordered to match.

5. Latent code bugs noticed (not fixed here)

Worth separate issues — flagging so they don't get lost:

• `send_message` (`spond.py:285`) is missing `await` on `self._continue_chat(chat_id, text)`. Also annotated `-> JSONDict` but can return `False` (line 295).
• `update_event` (`spond.py:454-455`) saves the API response to `self.events_update` but then `return self.events` — returns the unrelated cached list instead of the update result. Docstring says "json results of post command" which matches the intended behavior, so the bug is in the code, not the docstring.

Test plan

• Local `pytest` — 23 tests pass
• Local `ruff check` — clean
• Local `ruff format --check` — clean (with ruff 0.15.12)
• Local `pdoc -o /tmp/pdoc-out ./spond` — generates the expected file tree, new module-level docstring visible on `spond.html`, all base.py docstrings render, `get_events` param order matches signature
• Smoke-tested `import spond` — module-level docstring loads, `AuthenticationError` docstring intact
• CI: Python package matrix + new Publish API docs workflow (will need the Pages settings flip before Deploy can succeed)
• Post-merge verification: visit https://olen.github.io/Spond/ and confirm docs render

🤖 Generated with Claude Code