Skip to content

DOC: Replace reST cross-reference roles in docstrings with plain backticks#1782

Open
romanlutz wants to merge 2 commits into
microsoft:mainfrom
romanlutz:romanlutz/audit-rest-roles
Open

DOC: Replace reST cross-reference roles in docstrings with plain backticks#1782
romanlutz wants to merge 2 commits into
microsoft:mainfrom
romanlutz:romanlutz/audit-rest-roles

Conversation

@romanlutz
Copy link
Copy Markdown
Contributor

Why

PyRIT's docs build uses MyST (Markdown-flavoured), not reStructuredText.
reST cross-reference roles like :class:SeedPrompt, :func: oo, :meth:�ar etc. render as raw text under MyST and are inconsistent with the prevailing convention — plain double-backtick code spans inside Google-style docstrings (see e.g. pyrit/datasets/seed_datasets/remote/visual_leak_bench_dataset.py and pyrit/datasets/seed_datasets/remote/harmbench_multimodal_dataset.py).

A reviewer flagged this on pyrit/datasets/seed_datasets/remote/mossbench_dataset.py and it was fixed there in a follow-up commit. This PR audits and fixes the rest of the repo, and adds a style-guide rule to prevent recurrence.

What changed

Audit + fix (Part 1)

Searched pyrit/, tests/, doc/ for reST role syntax in docstrings/comments. Found 55 occurrences across 17 .py files (zero hits in .md/.ipynb):

Role Count
:class: 25
:func: 11
:meth: 10
:data: 7
:py:func: 2

Every occurrence was rewritten from :role:Name to Name. Pure docstring/comment text changes — no logic or signature changes.

Style rule (Part 2)

Added a "Code references in docstrings" subsection to .github/instructions/style-guide.instructions.md under Documentation Standards → Docstring Format. Its existing applyTo: '**/*.py' front-matter ensures Copilot picks it up for every Python file. The rule:

  • Forbids reST cross-reference roles in docstrings/comments.
  • Mandates plain double-backtick code spans (matches existing convention).
  • Notes the MyST {class}Name alternative only as a rare fallback — the default in PyRIT is plain backticks, not cross-references.

Also added a checklist item to the "Final Checklist" near the end of the file.

Verification

  • uv run ruff check — passes
  • uv run ruff format --check — all 17 files already formatted
  • uv run pre-commit run --files <changed> — all hooks pass (trailing whitespace, EOF, ruff, ty, etc.)
  • uv run pytest on changed-module test files — 146/146 passed
  • Re-ran the grep — 0 remaining reST role occurrences anywhere under pyrit/, tests/, or doc/.

romanlutz and others added 2 commits May 22, 2026 15:42
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.

1 participant