Repository navigation
Write test to detect unescaped double-underscore and single-underscore values in docstrings #1189
Description
These are almost always intended to refer to magic methods, but markdown/rst/etc interpret it as emphasis and remove the underscores. We should detect that this is happening and raise errors.
Metadata
Metadata
Assignees
Labels
introduces/modifies 1-2 concepts, should take 1-2 days max for an advanced contributorThis issue can be resolved by someone who is not familiar with the codebase. A good starting issue.Want to contribute to Cirq, but don't know quantum computing? This issue is for you.Zero to little experience with Cirq requiredA consensus emerged that this bug report, feature request, or other action should be worked on
Activity
Speed up param resolution
Speed up param resolution (#2394)
dabacon commentedon May 1, 2020
An example can be found in
https://cirq.readthedocs.io/en/stable/generated/cirq.phase_by.html
where we see an un-escaped
_phased_by_[-]Detect unescaped double-underscore and single-underscore values in docstrings[/-][+]Write test to detect unescaped double-underscore and single-underscore values in docstrings[/+]balopat commentedon Sep 22, 2020
As we're retiring sphinx, the work here is to check this behavior in devsite.
21 remaining items
matti-sarjala commentedon May 14, 2026
A small implementation boundary that might keep this issue manageable:
_phase_by_, by wrapping the literal method name in backticks in the source docstring.A conservative pattern could focus on names that look like Cirq protocol hooks:
_unitary__decompose__apply_unitary__phase_by__circuit_diagram_info__json_dict_The test does not need to understand all Markdown/RST. It could simply flag occurrences of these known literal names when they appear outside code formatting. That keeps the first version low-risk and avoids many false positives.
This would turn the current one-off rendering fix into a guardrail so future docstrings do not reintroduce the same problem.
prarthana-ma commentedon Sep 24, 2026
Hi @mhucka, would love to pick this up if it's still available!
I saw PR #8368 fixes the existing unescaped symbols, but it's not meant to catch new ones going forward. I'd like to take on that part, the test @matti-sarjala described above.
Plan: use
astto pull out actual docstrings (not just grep the whole file), check them against the known list of protocol names (_unitary_,_decompose_,_apply_unitary_,_phase_by_,_circuit_diagram_info_,_json_dict_, etc.), and flag any that aren't wrapped in backquotes, with the file and line number so it's easy to fix. I've already got a working version tested on some sample cases, so I can adapt it to the actual codebase once I'm on it.@WingCode I noticed you referenced this issue with a PR on your fork back in May, is that still active? Don't want to duplicate work if you're already on it.
Thanks!
mhucka commentedon Sep 30, 2026
@prarthana-ma Thank you for your interest! It's assigned to you now.
Fix missing backquotes around literal symbols (quantumlib#8368)
mhucka commentedon Nov 1, 2026
@prarthana-ma I'm going around and checking the statuses of things. Could you let us know where things stand with this work?
Fix missing backquotes around literal symbols (quantumlib#8368)
BretMishler commentedon Nov 10, 2026
I opened #8514, which adds a pylint checker for this. It flags unescaped
__foo__,_foo_,_foo_bar, andfoo_bar_symbols in docstrings anddocument()strings.@prarthana-ma, I noticed this is assigned to you, so apologies for the overlap. Happy to coordinate, or to step back if you already have something in progress.
@mhucka, there's an open scope question on the PR about whether test files should be checked too: #8514 (comment)