docs: remove PR/issue references from public docstrings#245
Merged
Conversation
The expanded docstrings landed in #237/#241 inlined references to issue and PR numbers (e.g. \"see #205\", \"PR #236 changes ...\", \"fixed in #235\"). Those references publish to the docs site via pdoc and rot the moment issues are renumbered, repos are renamed, or the codebase moves — exactly the kind of incidental-link maintainence burden the project's general rule against in-code issue references is meant to prevent. Rewrote each docstring to describe the behaviour/limitation directly in prose, so a reader of the published docs learns the same thing without having to chase a number into the issue tracker. Touched docstrings: - AuthenticationError (`spond/__init__.py`): dropped \"see #205\"; the surrounding bullet already explains the 2FA gap. - `Spond.__init__`: dropped \"see #205\"; replaced with \"Spond's TOTP flow is not yet supported\". - `Spond.get_events`: dropped the PR #236 forward-reference; replaced with a direct description of the cache-vs-direct trade-off. - `Spond.get_event`: dropped \"see #137 and #138\" and the PR #236 forward-reference; rewrote to describe how to reach events outside the default window directly. - `Spond.get_event_attendance_xlsx`: dropped \"see closed issue #227\"; the prose already names the limitation. - `Spond._get_entity`: dropped \"#136, fixed in #235\"; described the empty-cache behaviour directly. No code changes, no test changes, all 30 tests still pass.
The docstrings throughout `spond/` use the NumPy convention (`Parameters` heading followed by an `----` underline, parameter name on one line, type+description indented). pdoc supports that dialect but it's opt-in via `--docformat`; without the flag pdoc treats the section headings as plain text, so the rendered docs show all parameters running together as one flat paragraph. Add `--docformat numpy` to both invocations: - `.github/workflows/publish-docs.yml` so the hosted site renders with structured Parameters / Returns / Raises sections. - `README.md` so contributors running pdoc locally see the same output, with a note explaining why the flag is needed. Verified locally: with the flag, `get_events` renders as an `<h6>` header followed by a `<ul>` where each parameter is its own `<li>` with the name bolded and type in parentheses. Without it, the same docstring renders as a single paragraph of run-together text.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the quality and durability of the published API documentation by removing inline references to GitHub PR/issue numbers from public docstrings (which are rendered verbatim on the pdoc site), and replacing them with stable prose descriptions.
Changes:
- Rewrote several public docstrings to describe behavior/limitations directly, without “see #… / PR #…” references.
- Updated local and CI pdoc commands to use
--docformat numpyso NumPy-style docstring sections render as structured lists.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
spond/spond.py |
Replaces PR/issue references in method docstrings with prose explanations of caching/visibility limitations and empty-cache behavior. |
spond/__init__.py |
Removes an issue-number reference from AuthenticationError docstring while keeping the 2FA/TOTP limitation documented. |
README.md |
Updates pdoc usage examples and explains why --docformat numpy is used. |
.github/workflows/publish-docs.yml |
Ensures the published docs build uses pdoc --docformat numpy for consistent docstring rendering on GitHub Pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…tring Address Copilot review on #245: the docstring referenced `scheduled=true`, which is the raw HTTP API parameter name. The Python-facing knob is `include_scheduled` on `get_events()`. Mixing the two namespaces in a user-facing docstring is confusing — a reader could reasonably assume `get_event()` accepts a `scheduled` keyword arg. Rephrased to `include_scheduled=False` (the actual Python default that excludes those events from the cache).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The docstrings expanded in #237/#241 inlined references to issue and PR numbers ("see #205", "PR #236 changes ...", "fixed in #235"). Those references publish to https://olen.github.io/Spond/ via pdoc and rot the moment issues are renumbered or the repo moves — exactly the maintenance burden that the general no-PR-refs-in-source-comments rule is meant to prevent.
Rewrote each docstring to describe the behaviour/limitation directly in prose. A reader of the published docs learns the same thing without having to chase a number into the issue tracker.
Touched docstrings
Test plan
🤖 Generated with Claude Code