Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c3b5efb

Browse files
ScottCarda-MSScottCarda-MS
authored
Update Python Docs for qdk package (#3144)
Updates the doc strings in the `qdk` python package to use a standardized syntax (sphynx) for automated API documentation generation. The package was flattened to remove the `src/` folder as that causes issue for the documentation generation tool. Here is a preview of the generated docs: https://review.learn.microsoft.com/en-us/python/qdk/qdk?view=qsharp-py&branch=pr-en-us-105 Note that only the `qdk` section of the preview reflects code changes from this PR. The `qsharp` and `azure-quantum` in the preview are from the official docs.
1 parent 2fc02b1 commit c3b5efb

39 files changed

Lines changed: 385 additions & 280 deletions

‎source/pip/qsharp/interop/qiskit/__init__.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,21 @@
99
1010
Available backends:
1111
12-
:class:`~qsharp.interop.qiskit.QSharpBackend`
12+
- :class:`~qsharp.interop.qiskit.QSharpBackend`
1313
Runs any Qiskit ``QuantumCircuit`` using the Q# simulator. Supports
1414
noise-free simulation via QASM export and QIR compilation.
1515
16-
:class:`~qsharp.interop.qiskit.NeutralAtomBackend`
16+
- :class:`~qsharp.interop.qiskit.NeutralAtomBackend`
1717
Runs Qiskit circuits on the local NeutralAtomDevice simulator. Decomposes
1818
gates to the native ``{Rz, SX, CZ}`` gate set and optionally models
1919
per-gate noise (including qubit loss). Loss shots are exposed separately
2020
from accepted shots in the job result.
2121
22-
:class:`~qsharp.interop.qiskit.ResourceEstimatorBackend`
22+
- :class:`~qsharp.interop.qiskit.ResourceEstimatorBackend`
2323
Estimates quantum resources (qubits, T-gates, etc.) for a Qiskit circuit
2424
without running a full simulation.
2525
26-
:func:`~qsharp.interop.qiskit.estimate`
26+
- :func:`~qsharp.interop.qiskit.estimate`
2727
Convenience function that runs resource estimation on a Qiskit circuit
2828
and returns an :class:`~qsharp.estimator.EstimatorResult` directly, without
2929
needing to construct a backend or job manually.

‎source/qdk_package/.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
/build/
2-
/src/*.egg-info/
2+
/src/
3+
/*.egg-info/
4+
/doc/

‎source/qdk_package/pyproject.toml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,5 @@ all = [
3131
]
3232

3333
[tool.setuptools.packages.find]
34-
where = ["src"]
35-
36-
[tool.setuptools]
37-
package-dir = {"" = "src"}
34+
where = ["."]
3835

source/qdk_package/src/qdk/__init__.py renamed to source/qdk_package/qdk/__init__.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@
99
Optional extras install additional dependencies and submodules:
1010
1111
- ``azure`` — installs ``azure-quantum``, available as ``qdk.azure``.
12-
- ``qiskit`` — installs ``qiskit``, available as ``qdk.qiskit``.
13-
- ``cirq`` — installs ``cirq-core`` + ``cirq-ionq``, available as ``qdk.cirq``.
12+
- ``qiskit`` — installs ``qiskit`` and makes Qiskit interop functionality available as ``qdk.qiskit``.
13+
- ``cirq`` — installs ``cirq-core`` + ``cirq-ionq`` and makes Cirq interop functionality available as ``qdk.cirq``.
1414
- ``jupyter`` — installs ``qsharp-widgets`` + ``qsharp-jupyterlab``; exposes ``qdk.widgets``.
1515
1616
"""

source/qdk_package/src/qdk/applications/__init__.py renamed to source/qdk_package/qdk/applications/__init__.py

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,16 @@
44
# flake8: noqa F403
55
# pyright: ignore[reportWildcardImportFromLibrary]
66

7-
"""qdk.applications package: re-export of qsharp.applications symbols.
7+
"""Quantum applications for the Q# ecosystem.
88
9-
Requires installation: ``pip install \"qdk[applications]\"``.
9+
This module re-exports all public symbols from [qsharp.applications](:mod:`qsharp.applications`),
10+
making them available under the ``qdk.applications`` namespace.
11+
12+
Requires the ``applications`` extra: ``pip install "qdk[applications]"``.
1013
1114
Example:
12-
from qdk.applications import QSharpApplication
1315
16+
from qdk.applications import QSharpApplication
1417
"""
1518

1619
try:

source/qdk_package/src/qdk/applications/magnets.py renamed to source/qdk_package/qdk/applications/magnets.py

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,18 @@
44
# flake8: noqa F403
55
# pyright: ignore[reportWildcardImportFromLibrary]
66

7-
"""qdk.applications.magnets package: re-export of qsharp.applications.magnets symbols.
7+
"""Magnetic system applications for the Q# ecosystem.
88
9-
Requires installation: ``pip install \"qdk[applications]\"``.
9+
This module re-exports all public symbols from [qsharp.applications.magnets](:mod:`qsharp.applications.magnets`),
10+
making them available under the ``qdk.applications.magnets`` namespace. It
11+
provides classes for modeling and simulating magnetic systems such as the Ising
12+
model using quantum algorithms.
13+
14+
Requires the ``applications`` extra: ``pip install "qdk[applications]"``.
1015
1116
Example:
12-
from qdk.applications.magnets import IsingModel
1317
18+
from qdk.applications.magnets import IsingModel
1419
"""
1520

1621
try:

‎source/qdk_package/qdk/azure/__init__.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Copyright (c) Microsoft Corporation.
2+
# Licensed under the MIT License.
3+
4+
"""Azure Quantum integration for the Q# ecosystem.
5+
6+
This module re-exports all public symbols from [azure.quantum](:mod:`azure.quantum`),
7+
making them available under the ``qdk.azure`` namespace. The primary entry point is
8+
:class:`azure.quantum.Workspace`, which represents a connection to an Azure Quantum
9+
workspace.
10+
11+
Key exports:
12+
13+
- :class:`azure.quantum.Workspace` — connect to an Azure Quantum workspace and submit jobs.
14+
- :class:`azure.quantum.job.Job`, :class:`azure.quantum.job.Session` — job and session management.
15+
- :class:`azure.quantum.job.JobDetails`, ``JobStatus``, :class:`azure.quantum.job.SessionDetails`, :class:`azure.quantum.job.SessionStatus` — status and metadata types.
16+
- ``ItemType``, :class:`azure.quantum.job.SessionHost`, :class:`azure.quantum.job.SessionJobFailurePolicy` — configuration enumerations.
17+
18+
Usage:
19+
20+
from qdk import azure
21+
ws = azure.Workspace(...) # if upstream exposes Workspace at top-level
22+
23+
Requires the ``azure`` extra: ``pip install qdk[azure]``.
24+
"""
25+
26+
try:
27+
# Re-export the top-level azure.quantum names.
28+
from azure.quantum import * # pyright: ignore[reportWildcardImportFromLibrary]
29+
except Exception as ex:
30+
raise ImportError(
31+
"qdk.azure requires the azure extra. Install with 'pip install qdk[azure]'."
32+
) from ex

‎source/qdk_package/qdk/azure/argument_types.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Copyright (c) Microsoft Corporation.
2+
# Licensed under the MIT License.
3+
4+
"""Argument types for Azure Quantum job inputs.
5+
6+
This module re-exports all public symbols from
7+
[azure.quantum.argument_types](:mod:`azure.quantum.argument_types`),
8+
making them available under the ``qdk.azure.argument_types`` namespace.
9+
10+
Key exports:
11+
12+
- :class:`azure.quantum.argument_types.EmptyArray` — represents an empty typed array argument.
13+
- :class:`azure.quantum.argument_types.Pauli` — Pauli operator argument type (I, X, Y, Z).
14+
- :class:`azure.quantum.argument_types.Range` — integer range argument.
15+
- :class:`azure.quantum.argument_types.Result` — qubit measurement result argument (Zero or One).
16+
17+
Requires the ``azure`` extra: ``pip install qdk[azure]``.
18+
"""
19+
20+
try:
21+
from azure.quantum.argument_types import * # pyright: ignore[reportWildcardImportFromLibrary]
22+
except Exception as ex:
23+
raise ImportError(
24+
"qdk.azure requires the azure extra. Install with 'pip install qdk[azure]'."
25+
) from ex

‎source/qdk_package/qdk/azure/cirq.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Copyright (c) Microsoft Corporation.
2+
# Licensed under the MIT License.
3+
4+
"""Cirq integration for Azure Quantum.
5+
6+
This module re-exports all public symbols from [azure.quantum.cirq](:mod:`azure.quantum.cirq`),
7+
making them available under the ``qdk.azure.cirq`` namespace.
8+
9+
Key exports:
10+
11+
- :class:`azure.quantum.cirq.AzureQuantumService` — a ``cirq.Sampler``-compatible
12+
service that submits Cirq circuits to Azure Quantum targets.
13+
- :class:`azure.quantum.cirq.Job` — represents an Azure Quantum job submitted via Cirq.
14+
15+
Requires the ``azure`` and ``cirq`` extras: ``pip install "qdk[azure,cirq]"``.
16+
"""
17+
18+
try:
19+
from azure.quantum.cirq import * # pyright: ignore[reportWildcardImportFromLibrary]
20+
except Exception as ex:
21+
raise ImportError(
22+
"qdk.azure.cirq requires the azure and cirq extras. Install with 'pip install \"qdk[azure,cirq]\"'."
23+
) from ex

‎source/qdk_package/qdk/azure/job.py‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Copyright (c) Microsoft Corporation.
2+
# Licensed under the MIT License.
3+
4+
"""Job and session management for Azure Quantum.
5+
6+
This module re-exports all public symbols from [azure.quantum.job](:mod:`azure.quantum.job`),
7+
making them available under the ``qdk.azure.job`` namespace.
8+
9+
Key exports:
10+
11+
- :class:`azure.quantum.job.Job` — an Azure Quantum job, with methods to wait for and retrieve results.
12+
- :class:`azure.quantum.job.Session`, :class:`azure.quantum.job.SessionDetails`, :class:`azure.quantum.job.SessionHost` — grouped job session management.
13+
- :class:`azure.quantum.job.WorkspaceItem` — lower-level workspace item type.
14+
15+
Requires the ``azure`` extra: ``pip install qdk[azure]``.
16+
"""
17+
18+
try:
19+
from azure.quantum.job import * # pyright: ignore[reportWildcardImportFromLibrary]
20+
except Exception as ex:
21+
raise ImportError(
22+
"qdk.azure requires the azure extra. Install with 'pip install qdk[azure]'."
23+
) from ex

0 commit comments

Comments
 (0)