[docs] Correct Python docstrings and snippets that contradict the code

[udsy19]

Fixes #5181.

Nine places in the Python documentation state something the code does not do.
Each was verified against an installed cudaq 0.15.1 package before and after
the change. In every case the code is correct and the documentation is wrong,
so this PR changes only comments, docstrings and whitespace — no executable
line changes.

One of them fails quietly, which is why this is worth a PR rather than a nit:

The SampleResult iteration example in the specification prints wrong data
silently. algorithmic_primitives.rst uses for bits, count in counts:.
SampleResult iterates over bit-string keys, like a dict, so for the
two-qubit bell kernel the example demonstrates:

Observed: 0, 0
Observed: 1, 1

Python unpacked '00' into two characters; the real counts never appear, and
the output looks plausible next to the C++ tab's Observed: 00, 514. With
counts.items():

Observed: 00, 479
Observed: 11, 521

At any other qubit count the documented form raises
ValueError: too many values to unpack (expected 2).

The rest

• Two .. code-block:: python blocks in algorithmic_primitives.rst are not
  Python: one uses the C++ scope operator (cudaq::observe), the other splits
  an expression across two lines without parentheses. Both are SyntaxError.
  After this change, ast.parse succeeds on all nine Python code blocks in
  that file; before it, these two failed.
• Kernel.mz / mx / my document register_name; the parameter is
  regName. The documented name raises TypeError.
• cudaq.operators.custom.define documents op_id (it is id) and
  instantiate documents operator_id (it is op_id). Both raise TypeError.
• cudaq.translate says its result is "the circuit, without measurement
  operations". It is not: format="openqasm2" on a kernel containing mz(q)
  emits creg/measure, format="qir" emits __quantum__qis__mz calls, and
  the docstring's own example output shows those calls. The sentence is copied
  from cudaq.draw, where it is correct.
• SampleResult.__getitem__ documents a float return and returns int — as
  the nanobind-generated signature two lines above in the same __doc__
  already says, and as the sibling count() documents correctly.
• QuakeValue.slice documents start; the parameter is startIdx.
• The nine QuakeValue arithmetic dunders document
  Raises: RuntimeError: if the underlying QuakeValue type is not a float.
  No such error is raised: integer operands emit
  arith.muli/addi/subi/divsi, and __neg__ promotes to arith.negf.
  Integer support predates these Raises: lines, so the claim was never
  accurate; replaced with a note on the accepted operand types.
• cudaq.get_unitary's docstring code block wraps two lines in literal
  backticks and under-indents the trailing print, so it renders with the
  backticks visible and fails with SyntaxError if copied. Fixed; the block now
  extracts and runs, printing the Bell unitary.

One thing that is not a doc fix

Commit d7fabc860 adds cx and qvector to
.github/pre-commit/spelling_allowlist.txt. The literal backticks in the
get_unitary example were load-bearing: the python matrix in
spellcheck_config.yml skips docstring content between inline backticks, so
removing them exposes those two words. Both are CUDA-Q vocabulary and qvec was
already in the list. That is the only hunk outside docstrings and .rst.

It shares a commit with the unitary.py docstring fix rather than standing
alone, so dropping the commit would also drop one of the nine corrections. If
you would rather solve the spelling side another way, say so and I will split
the commit and drop only the allowlist hunk.

Overlaps I checked

• Move larger code blocks in docs into their own files Unitary Hack #2969 also rewrites the apply_noise block in python_api.rst, replacing
  it with a literalinclude whose extracted snippet has the indentation right.
  This PR therefore leaves python_api.rst alone entirely, so the two cannot
  conflict; see the scope note below.
• Add half‐open slicing support to QuakeValue #3017 implements QuakeValue.slice. I deliberately left the Returns:
  block alone so this does not conflict with it, and changed only the wrong
  parameter name, which Add half‐open slicing support to QuakeValue #3017 does not touch.
• Pass agent skill #4950 touches algorithmic_primitives.rst at lines 191-266 and 300-312;
  the hunks here are at 89, 543 and 586.
• [docs] refactoring examples.rst with standalone CI integration #2981 rewrites examples.rst, which carries a very similar defect in the
  deuteron parameter-sweep example. I have kept examples.rst out of this PR
  entirely and raised it there instead.
• default_ops.rst is untouched — [docs] Document givens_rotation and fermionic_swap operations #5162 is open on it.

Verification

cudaq 0.15.1 (aca5853a7), Python 3.13, macOS 26.5.1 arm64. Every claim above was
executed, both before and after.

pre-commit run --all-files --hook-stage pre-push was run on upstream/main
and on this branch. Both give the same result: 13 hooks pass, and
Check links in Markdown files fails on a pre-existing dead CI-badge URL in
README.md, a file this branch does not touch. pyspelling passes.

The Sphinx build was not run locally — conf.py needs autodoc against a full
source build. As a substitute I parsed both edited .rst files with docutils
before and after (identical diagnostics, nothing new), ast.parsed every
.. code-block:: python in the edited files, and extracted and executed the
two blocks that were re-indented.

---

Scope note: an earlier draft of this branch also re-indented the apply_noise example in python_api.rst. That change was dropped because open PR #2969 already replaces that block with a literalinclude. This PR deliberately leaves it alone.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.