Improve docstrings across all hand-written modules for pdoc#21
Merged
Conversation
Add comprehensive Google-style docstrings to every hand-written module so that the pdoc-generated API reference site is useful on its own. - Replace the one-line __init__.py module docstring with a full landing page (quick start, authentication, job submission examples, and a key-features overview with cross-reference links to every major symbol) - Update the Jinja template to match so regeneration preserves the landing page - Add Args, Returns, Raises, Yields, Examples, and Attributes sections to IonQClient, all exception classes, ClientExtension, EventHook, AsyncEventHook, HookTransport, SessionManager, all pagination helpers, both polling functions, ErrorRaisingTransport, and build_transport - Document module-level constants (RETRYABLE_STATUS_CODES, DEFAULT_MAX_RETRIES) and type aliases (Matrix2x2, Matrix4x4) with variable docstrings so they appear in the generated docs - Add exception hierarchy diagram to _exceptions module docstring - Add module-level usage examples to _extensions, _pagination, _polling, _session, and _gates
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
2 participants
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
Adds comprehensive Google-style docstrings to every hand-written module so the pdoc-generated API reference site (https://ionq.github.io/ionq-core-python/) is useful as standalone documentation.
Landing page (
__init__.py+ Jinja template):IonQClient,SessionManager,iter_jobs, etc.)Per-module improvements:
ionq_client.py-IonQClientnow has full Args, Returns, Raises, and three Examples (env var, explicit config, async context manager)_exceptions.py- Exception hierarchy diagram in the module docstring;APIErrorattributes (status_code,body,message,request_id) andRateLimitError.retry_afterdocumented;raise_for_statushas full Args/Raises_extensions.py- All 11ClientExtensionfields documented in an Attributes section;EventHook/AsyncEventHookprotocol methods have Args;HookTransporthas behavioral description and Args; module-level usage example_gates.py- Parameter conventions and type alias descriptions in module docstring; variable docstrings forMatrix2x2/Matrix4x4; Args/Returns/Examples on all four gate functions_pagination.py- All 4 public functions have Args, Yields, Raises; module-level example_polling.py-JobTimeoutError/JobFailedErrorattributes documented; bothwait_for_jobandasync_wait_for_jobhave Args/Returns/Raises; module-level example_session.py-SessionManagerclass docstring with constructor Args and sync/async context manager examples; all public methods documented_transport.py- Variable docstrings forRETRYABLE_STATUS_CODESandDEFAULT_MAX_RETRIES;ErrorRaisingTransportandbuild_transportfully documentedNo code logic was changed - only docstrings and the
__init__.pyJinja template.Test plan
uv run ruff checkpasses on all modified filesuv run ruff format --checkpasses on all modified filesuv run pytest- all 218 tests pass, 100% coverage maintaineduv run pdoc -o docs/ -d google ionq_coregenerates cleanlyIonQClient,ClientExtension,SessionManager,iter_jobs,wait_for_job, etc.) resolve to clickable anchors in the generated HTML:class:) appear in the rendered outputClientExtensionAttributes section renders all 11 field descriptionsImportant
Most code in
ionq_core/is auto-generated. Do not edit files underionq_core/api/,ionq_core/models/, orionq_core/client.py,errors.py,types.pydirectly.See CONTRIBUTING.md for details.