Update Python API Doc Strings

[ScottCarda-MS]

Update docstrings under qdk and convert qsharp shims to deprecation docstrings

For a preview of the docs after this change see: https://review.learn.microsoft.com/en-us/python/qdk/qdk?view=qsharp-py&branch=pr-en-us-105
Note that we may want to omit the qsharp package documentation going forward as it is now a deprecated package.

Summary

Following the migration of all package content from qsharp (under source/pip/) into qdk (under source/qdk_package/), this PR updates docstrings to reflect the new home of the code and fixes a large set of broken Sphinx cross-references throughout the qdk Python API documentation.

The core changes are:

1. Replace stale qsharp.* Sphinx cross-references in qdk docstrings with the correct qdk.* paths.
2. Fully qualify bare cross-references in module-level docstrings so they resolve in py2docfx output.
3. Repoint dead qdk._native.* cross-references at their public re-exports (and add public re-exports for three return types that didn't have one).
4. Convert per-file # Deprecated: use qdk.X instead comments in the qsharp shim into proper module docstrings so the deprecation hint shows up in help(), IDE tooltips, and Sphinx autodoc.
5. Refresh the top-level qdk/__init__.py docstring to give an overview of the package, its core submodules, optional extras, and its relationship to the legacy qsharp shim.

No behavioral changes. No exports were removed. While there are some public API changes that this work highlights would be good to have, this PR will focus on documentation changes and avoid making changes to the public API.

Public API additions

This PR previously made some changes to the public API that have been reverted. We want to avoid making those changes in this PR and a follow up team discussion and PR will be made to make the necessary changes.

Categories of change

qdk docstrings — qsharp -> qdk path corrections

Updated stale Sphinx cross-references that still pointed at the pre-migration qsharp.* namespace:

• Replaced :class:\~qsharp.X`, :func:`~qsharp.X`, and :attr:`~qsharp.X`references with the correct~qdk.X` paths in qdk/_interpreter.py, qdk/_context.py, qdk/openqasm/_circuit.py, qdk/cirq/init.py, qdk/qiskit/init.py, qdk/qiskit/jobs/qsjob.py, qdk/qiskit/jobs/qsjobset.py, and qdk/estimator/_estimator.py.
• Updated from qsharp.X import Y and qsharp.compile("...") examples in docstrings to use qdk.* paths in qdk/openqasm/_compile.py, qdk/_interpreter.py, and qdk/qiskit/backends/neutral_atom_backend.py.
• Changed text references to qsharp.Result to qdk.Result in qdk/cirq/_result.py.
• Reworded "Disable qsharp Python telemetry" to "Disable QDK Python telemetry" in qdk/telemetry.py. The environment variable name (QSHARP_PYTHON_TELEMETRY) is unchanged for back-compat.

qdk docstrings — fully-qualified Sphinx cross-references

py2docfx does not respect __all__ when resolving bare :class: / :func: references in docstrings, so module-level docstrings that listed unqualified names (like :func:\init``) produced unresolved xrefs. These have been fully qualified throughout:

• qdk/init.py — top-level docstring.
• qdk/qsharp.py — Key exports list.
• qdk/_types.py — Types defined here list.
• qdk/_interpreter.py — module docstring + init, compile, circuit docstrings.
• qdk/_context.py — Context.__init__, Context.circuit, Context.compile docstrings.
• qdk/openqasm/init.py — Key exports list.
• qdk/openqasm/_circuit.py, qdk/openqasm/_compile.py, qdk/openqasm/_run.py — return-type and exception cross-references.

qdk docstrings — repointed away from private qdk._native.*

qdk._native is the Rust extension and is not documented, so cross-references to it are dead links. Each was repointed at its public re-export:

Was	Now	Notes
qdk._native.QasmError	qdk.openqasm.QasmError	Already publicly re-exported.
qdk._native.OutputSemantics	qdk.openqasm.OutputSemantics	Already publicly re-exported.
qdk._native.ProgramType	qdk.openqasm.ProgramType	Already publicly re-exported.
qdk._native.Circuit	qdk.qsharp.Circuit	New public re-export added in this PR.

Three additional return types had no public path at all, and have been re-exported from qdk.qsharp:

• Circuit — return type of qdk.qsharp.circuit().
• QirInputData — return type of qdk.qsharp.compile() and qdk.openqasm.compile().
• Config — return type of qdk.qsharp.init().

These also unblock removing the qdk._native.X references in docstrings.

qdk docstrings — method/attribute self-reference cleanup

py2docfx does not generate per-method uids for the page describing a class, so :meth:\result`from insideclass QsJob:doesn't resolve. Such self-references have been converted to plain backticks (e.g. ``result()` ``):

• qdk/qiskit/jobs/qsjob.py
• qdk/qiskit/jobs/qsjobset.py
• qdk/qiskit/backends/qsharp_backend.py
• qdk/qiskit/backends/re_backend.py
• qdk/qiskit/backends/neutral_atom_backend.py
• qdk/cirq/_result.py
• qdk/applications/magnets/utilities/hypergraph.py
• qdk/applications/magnets/utilities/pauli.py
• qdk/applications/magnets/trotter/trotter.py

qdk docstrings — qre cleanup (no API change)

Limited to docstring text fixes — public surface unchanged:

• Fixed :param ctx (Context): annotations that should have read (ISAContext) in qdk/qre/_isa_enumeration.py.
• Fixed (Node | None) and (Node) parameter annotations that should have read (ISAQuery | None) / (ISAQuery) in qdk/qre/_instruction.py. The Node | None form was also being mis-parsed by py2docfx into a malformed nested <xref:>.
• Removed bare BindingNode references from the public ISATransform.bind docstring.
• Rewrote Returns: _InstructionSourceNodeReference: / default (Optional[_InstructionSourceNodeReference]) docstring annotations as descriptive prose since the type is private. The annotations on the actual method signatures are unchanged.

A number of qre docs xrefs are still unresolved after this pass — see Known limitations of py2docfx below.

Top-level qdk/__init__.py docstring

The top-level docstring was rewritten to introduce QDK as the unified Python entry point, list the always-available core submodules (qdk.qsharp, qdk.openqasm, qdk.simulation, qdk.estimator, qdk.qre, qdk.code), enumerate the convenience re-exports at the package root, list optional extras (qdk[azure], qdk[qiskit], qdk[cirq], qdk[jupyter]), and note the relationship to the deprecated qsharp shim.

qsharp shim — deprecation comments converted to docstrings

All ~37 shim files in source/pip/qsharp/ had a leading # Deprecated: use qdk.X instead (or # Deprecation shim - delegates to qdk.X) comment. These have been converted to proper module docstrings of the form """Deprecated. Use :mod:\qdk.X` instead."""` so the deprecation hint shows up in:

• help(qsharp.X) output
• IDE tooltips and hover documentation
• Sphinx autodoc extraction

The top-level pip/qsharp/init.py already has a proper docstring with migration guidance and a DeprecationWarning; that file was not changed.

Functional behavior of every shim is unchanged.

What was intentionally not changed

• Telemetry event names ("qsharp.run", "qsharp.compile", ...) — these are stable analytics identifiers.
• Environment variable names (QSHARP_PYTHON_TELEMETRY, QSHARP_PYTHON_AI_KEY, ...) — public stable contract.
• Internal class / function / attribute names that legitimately reference Q# the language, such as QSharpError, QSharpBackend, QSharpApplication, __qsharp_class, _qsharp_value_to_python_value.
• qsharp.json — actual project manifest filename.
• External pip package names: qsharp_widgets, qsharp-widgets, qsharp-jupyterlab.

Known limitations of py2docfx

A number of cross-references remain unresolved in the generated YAML output but are not source-fixable without changing the public API surface. They are noted here so reviewers don't expect this PR to address them:

• Bare leaf names in signature renderings. py2docfx renders type annotations on function/method signatures using only the leaf name (e.g. Result, Pauli, Circuit, EstimatorResult, LogicalCounts, EstimationTableEntry, ConstraintBound) when the type is defined in or imported into the same module, regardless of __all__. The pages exist at the qualified paths; the xrefs from inside signature blocks just don't link.
• Enum members. py2docfx does not generate per-enum-member uids, so qdk.qsharp.CircuitGenerationMethod.ClassicalEval etc. don't resolve.
• External / cross-package references (azure.quantum.*, cirq.*, pandas.DataFrame, matplotlib.figure.Figure, datetime.datetime, builtins like int / bool / typing.*) — these need an xrefmap to be configured at the docs pipeline level.
• qdk.qre._Context, qdk.qre.TraceParameters, qdk.qre.Instruction, qdk.qre.models.ISA, qdk.qre.models.ISAContext, _InstructionSourceNodeReference — fixing each of these would require either renaming a private symbol to public, adding a TypeVar to __all__, or re-exporting a Rust-side type from additional submodules. Out of scope for this PR.

Tooling note

The python-doc-gen tool that consumes these docstrings (py2docfx) has a roughly 30-minute build time, no local validation, no --strict mode that flags unresolved xrefs as errors, and several known limitations (listed above) that mean a "valid Sphinx docstring" is not necessarily a "valid py2docfx docstring." Worth a discussion separately about whether to invest in a faster / more transparent doc generation toolchain (e.g. Sphinx + intersphinx with nitpicky mode), since the current iteration loop is a significant productivity drag for any non-trivial docstring change.