Skip to content

docs(qdp): improve generated Markdown rendering - #1456

Merged
400Ping merged 1 commit into
apache:mainfrom
viiccwen:qdp-docstring-markdown
Aug 8, 2026
Merged

docs(qdp): improve generated Markdown rendering#1456
400Ping merged 1 commit into
apache:mainfrom
viiccwen:qdp-docstring-markdown

Conversation

@viiccwen

Copy link
Copy Markdown
Contributor

Related Issues

Part of #1358
Related to #1361

Changes

  • Bug fix
  • New feature
  • Refactoring
  • Documentation
  • Test
  • CI/CD pipeline
  • Other

Why

QDP source docstrings contain reStructuredText roles and unfenced usage examples that do not render cleanly in the generated Docusaurus API reference.

This causes references such as :meth: and :class: to appear literally and makes Python usage examples harder to distinguish from surrounding prose.

How

  • Replace reStructuredText roles with Markdown-compatible inline code in QDP docstrings.
  • Wrap the QdpBenchmark usage example in a fenced Python code block.
  • Wrap the QuantumDataLoader usage example in a fenced Python code block.
  • Keep the changes documentation-only without modifying runtime behavior or the public API surface.

The changes are limited to:

  • qdp/qdp-python/qumat_qdp/_backend.py
  • qdp/qdp-python/qumat_qdp/api.py
  • qdp/qdp-python/qumat_qdp/loader.py
  • qdp/qdp-python/qumat_qdp/tensor.py

Validation

  • Generated the QDP Python API reference with pydoc-markdown.
  • Confirmed the usage examples render as Python code blocks.
  • Confirmed reStructuredText role markers no longer appear in the generated Markdown.
  • Existing QDP Python tests: 7 passed, 6 skipped because the native extension was not built.

Checklist

  • Added or updated unit tests for all changes — not applicable; documentation-only change
  • Added or updated documentation for all changes

Signed-off-by: viiccwen <vicwen@apache.org>
@viiccwen
viiccwen requested a review from 400Ping as a code owner July 31, 2026 08:54
@rich7420

rich7420 commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

LGTM. Diff is docstring/Markdown formatting only, no logic changes. ruff check/ruff format --check pass. pydoc-markdown output has balanced fences and zero remaining RST roles. Related tests (testing/qdp_python/, testing/qumat/test_qdp_module.py) pass, 113 passed.

Minor: loader.py/api.py usage examples call torch.from_dlpack without importing torch. Pre-existing, not introduced here. Worth a follow-up fix, not blocking.

@400Ping
400Ping merged commit 9abce4b into apache:main Aug 8, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants