Sccarda/python docs update

.gitignore

@@ -15,10 +15,12 @@ __pycache__/
 /source/fuzz/artifacts
 /source/fuzz/coverage
 /source/fuzz/Cargo.lock
+/source/pip/doc
 /source/samples_test/src/tests/*_generated.rs
 .mypy_cache/
 .pytest_cache/
 .idea/
 *.so
 samples/scratch/
 *.pyd
+/python_doc/

source/pip/qsharp/_adaptive_pass.py

@@ -292,13 +292,13 @@ def run(
     ) -> AdaptiveProgram:
         """Process module and return the AdaptiveProgram.
 
-        Args:
-            mod: The QIR module to process.
-            noise: Optional NoiseConfig. When provided, noise intrinsic calls
-                are resolved to correlated noise ops using the intrinsics table.
-            noise_intrinsics: Optional dict mapping noise intrinsic callee names
-                to noise table IDs. Takes precedence over ``noise`` if both are
-                given.
+        :param mod: The QIR module to process.
+        :param noise: Optional NoiseConfig. When provided, noise intrinsic calls
+            are resolved to correlated noise ops using the intrinsics table.
+        :param noise_intrinsics: Optional dict mapping noise intrinsic callee names
+            to noise table IDs. Takes precedence over ``noise`` if both are given.
+        :return: The processed adaptive program.
+        :rtype: AdaptiveProgram
         """
         if mod.get_flag("arrays"):
             raise ValueError("QIR arrays are not currently supported.")

source/pip/qsharp/_device/_atom/__init__.py

@@ -244,7 +244,7 @@ def simulate(
             If `None` (default), the GPU simulator will be tried first, falling back to
             CPU if a suitable GPU device could not be located.
         :param seed: An optional random seed for reproducibility.
-        :returns: The results of each shot of the simulation as a list.
+        :return: The results of each shot of the simulation as a list.
         """
 
         from ._validate import ValidateNoConditionalBranches

source/pip/qsharp/_device/_atom/_scheduler.py

@@ -147,13 +147,11 @@ class MoveGroup:
     """
     Represents a group of moves that can be done at the same time.
 
-    Attributes:
-        moves (set): A set of moves that can be performed in parallel.
-        scale_factor (Optional[tuple[Fraction, Fraction]]): A tuple of fractions
-            representing the scale factors in the row and col axes between
-            moves. `None`, if there is a single element in the move set.
-        ref_move (Move): A move used as a representative of the group, used
-            to test compatibility of other moves with the group.
+    ``moves`` is the set of moves that can be performed in parallel.
+    ``scale_factor`` is a tuple of fractions representing the scale factors in the
+    row and col axes between moves, or ``None`` if there is a single element in the set.
+    ``ref_move`` is a move used as a representative of the group to test compatibility
+    of other moves.
     """
 
     __slots__ = ("moves", "scale_factor", "ref_move")
@@ -170,8 +168,7 @@ def add(self, move: Move):
         """
         Adds a move to this move group.
 
-        Args:
-            move (Move): The move to add.
+        :param move: The move to add.
         """
 
         # A move group with a single move doesn't have an associated scale factor.
@@ -193,23 +190,17 @@ class MoveGroupPool:
     """A data structure that takes individual moves as input and organizes them
     into groups of moves that can be executed in parallel.
 
-    Attributes:
-        moves: A set containing all the moves in the move-group pool.
-        move_group_candidates: A dict organizing the move-group candidates
-            by scale factor.
-        parity: The parity of source and destination columns of all the moves
-            in this pool.
-        direction: The up/down and left/right direction of all the moves
-            in this pool.
+    ``moves`` contains all moves in the pool. ``move_group_candidates`` is a dict
+    organizing the move-group candidates by scale factor. ``parity`` is the parity
+    of source and destination columns of all moves in the pool. ``direction`` is the
+    up/down and left/right direction of all moves in the pool.
     """
 
     def __init__(self):
-        """Initializes a move-group pool for moves of the given `parity` and `direction`.
-        Args:
-            parity: The parity of source and destination columns of all the moves
-                in this pool.
-            direction: The up/down and left/right direction of all the moves
-                in this pool.
+        """Initializes a move-group pool for moves of the given ``parity`` and ``direction``.
+
+        :param parity: The parity of source and destination columns of all the moves in this pool.
+        :param direction: The up/down and left/right direction of all the moves in this pool.
         """
         self.moves: Optional[list[Move]] = []
         self.move_group_candidates: dict[MoveGroupScaleFactor, list[MoveGroup]] = (
@@ -235,9 +226,9 @@ def largest_move_group_candidate(self) -> Optional[MoveGroup]:
 
     def add(self, move: Move):
         """Adds a move to the move-group pool.
-        Args:
-            move: The move to add. It must be of the same parity and direction as
-                the rest of the moves in this pool.
+
+        :param move: The move to add. It must be of the same parity and direction as
+            the rest of the moves in this pool.
         """
         assert self.moves is not None
 
@@ -285,9 +276,9 @@ def add(self, move: Move):
         self.moves.append(move)
 
     def try_take(self, number_of_moves: int) -> list[Move]:
-        """Take up to `number_of_moves` from the largest move group candidate.
-        Args:
-            number_of_moves: The number of moves to take from this pool.
+        """Take up to ``number_of_moves`` from the largest move group candidate.
+
+        :param number_of_moves: The number of moves to take from this pool.
         """
         # Once we start taking moves from the MoveGroupPool, we don't need to add
         # new moves. So we set `self.moves` to `None` as a safety measure.
@@ -352,12 +343,10 @@ class MoveScheduler:
     target zone and builds an iterator that returns groups of moves
     that can be executed in parallel.
 
-    Attributes:
-        device: An object containing information about the device.
-        zone: The zone the moves will be scheduled to.
-        available_dst_locations: The available destinations in the `zone`.
-        partial_moves: The moves that haven't been assigned a destination location.
-        disjoint_pools: A list containing one pool of move-groups for each parity and direction.
+    ``device`` contains information about the device. ``zone`` is the target zone.
+    ``available_dst_locations`` holds the available destinations in the zone.
+    ``partial_moves`` are moves not yet assigned a destination. ``disjoint_pools``
+    is a list containing one pool of move-groups for each parity and direction.
     """
 
     def __init__(
@@ -368,10 +357,10 @@ def __init__(
     ):
         """Initializes the move scheduler from a device, a target zone,
         and a list of qubits to move to that target zone.
-        Args:
-            device: An object containing information about the device.
-            zone: The zone the moves will be scheduled to.
-            qubits_to_move: A list of qubits to move.
+
+        :param device: An object containing information about the device.
+        :param zone: The zone the moves will be scheduled to.
+        :param qubits_to_move: A list of qubits to move.
         """
         self.device = device
         self.zone = zone

source/pip/qsharp/_device/_device.py

@@ -58,11 +58,9 @@ def get_home_loc(self, qubit_id: int) -> tuple[int, int]:
         """
         Get the home location (row, column) of the qubit with the given id.
 
-        Args:
-            qubit_id (int): The id of the qubit.
-
-        Returns:
-            tuple[int, int]: The (row, column) location of the qubit.
+        :param qubit_id: The id of the qubit.
+        :return: The (row, column) location of the qubit.
+        :rtype: tuple[int, int]
         """
         if qubit_id < 0 or qubit_id >= len(self.home_locs):
             raise ValueError(f"Qubit id {qubit_id} is out of range")
@@ -72,11 +70,9 @@ def get_ordering(self, qubit_id: int) -> int:
         """
         Get the ordering index of the qubit with the given id.
 
-        Args:
-            qubit_id (int): The id of the qubit.
-
-        Returns:
-            int: The ordering index of the qubit.
+        :param qubit_id: The id of the qubit.
+        :return: The ordering index of the qubit.
+        :rtype: int
         """
         if qubit_id < 0 or qubit_id >= len(self.home_locs):
             raise ValueError(f"Qubit id {qubit_id} is out of range")
@@ -87,44 +83,43 @@ def get_register_zones(self) -> list[Zone]:
         """
         Get the register zones in the device.
 
-        Returns:
-            list[Zone]: The register zones.
+        :return: The register zones.
+        :rtype: list[Zone]
         """
         return [zone for zone in self.zones if zone.type == ZoneType.REG]
 
     def get_interaction_zones(self) -> list[Zone]:
         """
         Get the interaction zones in the device.
 
-        Returns:
-            list[Zone]: The interaction zones.
+        :return: The interaction zones.
+        :rtype: list[Zone]
         """
         return [zone for zone in self.zones if zone.type == ZoneType.INTER]
 
     def get_measurement_zones(self) -> list[Zone]:
         """
         Get the measurement zones in the device.
 
-        Returns:
-            list[Zone]: The measurement zones.
+        :return: The measurement zones.
+        :rtype: list[Zone]
         """
         return [zone for zone in self.zones if zone.type == ZoneType.MEAS]
 
     def compile(self, program: str) -> QirInputData:
         """
         Compile the given program for the device.
 
-        Args:
-            program (str): The program to compile.
+        :param program: The program to compile.
         """
         raise NotImplementedError("Subclasses must implement compile")
 
     def as_dict(self) -> dict:
         """
         Get the device layout as a dictionary.
 
-        Returns:
-            dict: The device layout as a dictionary.
+        :return: The device layout as a dictionary.
+        :rtype: dict
         """
         return {
             "cols": self.column_count,
@@ -138,7 +133,7 @@ def get_layout(self) -> dict:
         """
         Get the device layout as a dictionary.
 
-        Returns:
-            dict: The device layout as a dictionary.
+        :return: The device layout as a dictionary.
+        :rtype: dict
         """
         return self.as_dict()

source/pip/qsharp/_fs.py

@@ -18,11 +18,9 @@ def read_file(path: str) -> Tuple[str, str]:
     """
     Read the contents of a file.
 
-    Args:
-        path (str): The path to the file.
-
-    Returns:
-        Tuple[str, str]: A tuple containing the path and the file contents.
+    :param path: The path to the file.
+    :return: A tuple containing the path and the file contents.
+    :rtype: Tuple[str, str]
     """
     with open(path, mode="r", encoding="utf-8-sig") as f:
         return (path, f.read())
@@ -33,15 +31,13 @@ def list_directory(dir_path: str) -> List[Dict[str, str]]:
     Lists the contents of a directory and returns a list of dictionaries,
     where each dictionary represents an entry in the directory.
 
-    Args:
-        dir_path (str): The path of the directory to list.
-
-    Returns:
-        List[Dict[str, str]]: A list of dictionaries representing the entries
-        in the directory. Each dictionary contains the following keys:
-        - "path": The full path of the entry.
-        - "entry_name": The name of the entry.
-        - "type": The type of the entry: "file", "folder", or "unknown".
+    :param dir_path: The path of the directory to list.
+    :return: A list of dictionaries representing the entries in the directory.
+        Each dictionary contains the following keys:
+        - ``"path"``: The full path of the entry.
+        - ``"entry_name"``: The name of the entry.
+        - ``"type"``: The type of the entry: ``"file"``, ``"folder"``, or ``"unknown"``.
+    :rtype: List[Dict[str, str]]
     """
 
     def map_dir(e: str) -> Dict[str, str]:
@@ -63,12 +59,10 @@ def resolve(base: str, path: str) -> str:
     """
     Resolves a relative path with respect to a base path.
 
-    Args:
-        base (str): The base path.
-        path (str): The relative path.
-
-    Returns:
-        str: The resolved path.
+    :param base: The base path.
+    :param path: The relative path.
+    :return: The resolved path.
+    :rtype: str
     """
     return os.path.normpath(join(base, path))
 
@@ -77,11 +71,9 @@ def exists(path) -> bool:
     """
     Check if a file or directory exists at the given path.
 
-    Args:
-        path (str): The path to the file or directory.
-
-    Returns:
-        bool: True if the file or directory exists, False otherwise.
+    :param path: The path to the file or directory.
+    :return: ``True`` if the file or directory exists, ``False`` otherwise.
+    :rtype: bool
     """
     return os.path.exists(path)
 
@@ -90,11 +82,9 @@ def join(path: str, *paths) -> str:
     """
     Joins one or more path components intelligently.
 
-    Args:
-        path (str): The base path.
-        *paths (str): Additional path components to be joined.
-
-    Returns:
-        str: The concatenated path.
+    :param path: The base path.
+    :param *paths: Additional path components to be joined.
+    :return: The concatenated path.
+    :rtype: str
     """
     return os.path.join(path, *paths)

source/pip/qsharp/_http.py

@@ -13,18 +13,14 @@ def fetch_github(owner: str, repo: str, ref: str, path: str) -> str:
     """
     Fetches the content of a file from a GitHub repository.
 
-    Args:
-        owner (str): The owner of the GitHub repository.
-        repo (str): The name of the GitHub repository.
-        ref (str): The reference (branch, tag, or commit) of the repository.
-        path (str): The path to the file within the repository.
-
-    Returns:
-        str: The content of the file as a string.
-
-    Raises:
-        urllib.error.HTTPError: If there is an error fetching the file from GitHub.
-        urllib.error.URLError: If there is an error with the URL.
+    :param owner: The owner of the GitHub repository.
+    :param repo: The name of the GitHub repository.
+    :param ref: The reference (branch, tag, or commit) of the repository.
+    :param path: The path to the file within the repository.
+    :return: The content of the file as a string.
+    :rtype: str
+    :raises urllib.error.HTTPError: If there is an error fetching the file from GitHub.
+    :raises urllib.error.URLError: If there is an error with the URL.
     """
 
     import urllib.request