Fix formatting in docstrings. (#222)

src/hipscat/catalog/association_catalog/partition_join_info.py

@@ -106,10 +106,11 @@ def write_to_metadata_files(self, catalog_path: FilePointer = None, storage_opti
     def write_to_csv(self, catalog_path: FilePointer = None, storage_options: dict = None):
         """Write all partition data to CSV files.
 
-        Two files will be written::
-        - partition_info.csv - covers all primary catalog pixels, and should match the file structure
-        - partition_join_info.csv - covers all pairwise relationships between primary and
-          join catalogs.
+        Two files will be written:
+
+            - partition_info.csv - covers all primary catalog pixels, and should match the file structure
+            - partition_join_info.csv - covers all pairwise relationships between primary and
+              join catalogs.
 
         Args:
             catalog_path: FilePointer to the directory where the

src/hipscat/catalog/healpix_dataset/healpix_dataset.py

@@ -17,7 +17,9 @@ class HealpixDataset(Dataset):
     """A HiPSCat dataset partitioned with a HEALPix partitioning structure.
 
     Catalogs of this type are partitioned based on the ra and dec of the points with each partition
-    containing points within a given HEALPix pixel. The files are in the form 'Norder=/Dir=/Npix=.parquet'.
+    containing points within a given HEALPix pixel. The files are in the form::
+
+        Norder=/Dir=/Npix=.parquet
     """
 
     CatalogInfoClass: TypeAlias = BaseCatalogInfo

src/hipscat/inspection/almanac_info.py

@@ -60,12 +60,12 @@ def get_default_dir() -> str:
 
         This is set via the environment variable: HIPSCAT_ALMANAC_DIR
 
-        To set this in a linux-like environment, use a command like:
+        To set this in a linux-like environment, use a command like::
 
             export HIPSCAT_ALMANAC_DIR=/data/path/to/almanacs
 
         This will also attempt to expand any environment variables WITHIN the default
-        directory environment variable. This can be useful in cases where:
+        directory environment variable. This can be useful in cases where::
 
             $HIPSCAT_ALMANAC_DIR=$HIPSCAT_DEFAULT_DIR/almanacs/
         """

src/hipscat/io/file_io/file_io.py

@@ -270,8 +270,8 @@ def read_fits_image(map_file_pointer: FilePointer, storage_options: Union[Dict[A
         file_pointer: location of file to be written
         storage_options: dictionary that contains abstract filesystem credentials
     Returns:
-        histogram (:obj:`np.ndarray`): one-dimensional numpy array of long integers where the
-            value at each index corresponds to the number of objects found at the healpix pixel.
+        one-dimensional numpy array of long integers where the
+        value at each index corresponds to the number of objects found at the healpix pixel.
     """
     file_system, map_file_pointer = get_fs(file_pointer=map_file_pointer, storage_options=storage_options)
     with tempfile.NamedTemporaryFile() as _tmp_file:

src/hipscat/io/file_io/file_pointer.py

@@ -9,8 +9,8 @@
 
 def get_file_protocol(pointer: FilePointer) -> str:
     """Method to parse filepointer for the filesystem protocol.
-        if it doesn't follow the pattern of protocol://pathway/to/file, then it
-        assumes that it is a localfilesystem.
+    If it doesn't follow the pattern of protocol://pathway/to/file, then it
+    assumes that it is a localfilesystem.
 
     Args:
         pointer: filesystem pathway pointer
@@ -33,7 +33,7 @@ def get_fs(
         file_pointer: filesystem pathway
         storage_options: dictionary that contains abstract filesystem credentials
     Raises:
-        ImportError if environment cannot import necessary libraries for
+        ImportError: if environment cannot import necessary libraries for
             fsspec filesystems.
     """
     if storage_options is None:
@@ -50,15 +50,17 @@ def get_fs(
 
 
 def get_file_pointer_for_fs(protocol: str, file_pointer: FilePointer) -> FilePointer:
-    """Creates the filepathway from the file_pointer. Will strip the protocol so that
-            the file_pointer can be accessed from the filesystem
-        abfs filesystems DO NOT require the account_name in the pathway
-        s3 filesystems DO require the account_name/container name in the pathway
+    """Creates the filepathway from the file_pointer.
+
+    This will strip the protocol so that the file_pointer can be accessed from
+    the filesystem:
+
+        - abfs filesystems DO NOT require the account_name in the pathway
+        - s3 filesystems DO require the account_name/container name in the pathway
 
     Args:
         protocol: str filesytem protocol, file, abfs, or s3
         file_pointer: filesystem pathway
-
     """
     if not isinstance(file_pointer, str):
         file_pointer = str(file_pointer)
@@ -105,7 +107,13 @@ def get_basename_from_filepointer(pointer: FilePointer) -> str:
 
 def strip_leading_slash_for_pyarrow(pointer: FilePointer, protocol: str) -> FilePointer:
     """Strips the leading slash for pyarrow read/write functions.
-    This is required for their filesystem abstraction
+    This is required for pyarrow's underlying filesystem abstraction.
+
+    Args:
+        pointer: `FilePointer` object
+
+    Returns:
+        New file pointer with leading slash removed.
     """
     if protocol != "file" and str(pointer).startswith("/"):
         pointer = FilePointer(str(pointer).replace("/", "", 1))
@@ -203,7 +211,7 @@ def get_directory_contents(
 ) -> List[FilePointer]:
     """Finds all files and directories in the specified directory.
 
-    NBL This is not recursive, and will return only the first level of directory contents.
+    NB: This is not recursive, and will return only the first level of directory contents.
 
     Args:
         pointer: File Pointer in which to find contents

src/hipscat/io/paths.py

@@ -32,11 +32,11 @@ def pixel_directory(
     """Create path pointer for a pixel directory. This will not create the directory.
 
     One of pixel_number or directory_number is required. The directory name will
-    take the HiPS standard form of:
+    take the HiPS standard form of::
 
         <catalog_base_dir>/Norder=<pixel_order>/Dir=<directory number>
 
-    Where the directory number is calculated using integer division as:
+    Where the directory number is calculated using integer division as::
 
         (pixel_number/10000)*10000
 
@@ -64,7 +64,8 @@ def pixel_directory(
 
 
 def get_healpix_from_path(path: str) -> HealpixPixel:
-    """Find the `pixel_order` and `pixel_number` from a string like the following::
+    """Find the `pixel_order` and `pixel_number` from a string like the
+    following::
 
         Norder=<pixel_order>/Dir=<directory number>/Npix=<pixel_number>.parquet
 
@@ -85,13 +86,14 @@ def get_healpix_from_path(path: str) -> HealpixPixel:
 
 
 def pixel_catalog_file(catalog_base_dir: FilePointer, pixel_order: int, pixel_number: int) -> FilePointer:
-    """Create path *pointer* for a pixel catalog file. This will not create the directory or file.
+    """Create path *pointer* for a pixel catalog file. This will not create the directory
+    or file.
 
-    The catalog file name will take the HiPS standard form of:
+    The catalog file name will take the HiPS standard form of::
 
         <catalog_base_dir>/Norder=<pixel_order>/Dir=<directory number>/Npix=<pixel_number>.parquet
 
-    Where the directory number is calculated using integer division as:
+    Where the directory number is calculated using integer division as::
 
         (pixel_number/10000)*10000
 
@@ -113,7 +115,7 @@ def create_hive_directory_name(base_dir, partition_token_names, partition_token_
     """Create path *pointer* for a directory with hive partitioning naming.
     This will not create the directory.
 
-    The directory name will have the form of:
+    The directory name will have the form of::
 
         <catalog_base_dir>/<name_1>=<value_1>/.../<name_n>=<value_n>
 
@@ -132,7 +134,7 @@ def create_hive_directory_name(base_dir, partition_token_names, partition_token_
 def create_hive_parquet_file_name(base_dir, partition_token_names, partition_token_values):
     """Create path *pointer* for a single parquet with hive partitioning naming.
 
-    The file name will have the form of:
+    The file name will have the form of::
 
         <catalog_base_dir>/<name_1>=<value_1>/.../<name_n>=<value_n>.parquet
 

src/hipscat/io/write_metadata.py

@@ -94,8 +94,10 @@ def write_partition_info(
         catalog_base_dir (str): base directory for catalog, where file will be written
         destination_healpix_pixel_map (dict):  dictionary that maps the HealpixPixel to a
             tuple of origin pixel information:
-            - 0 - the total number of rows found in this destination pixel
-            - 1 - the set of indexes in histogram for the pixels at the original healpix order
+
+                - 0 - the total number of rows found in this destination pixel
+                - 1 - the set of indexes in histogram for the pixels at the original healpix order
+
         storage_options: dictionary that contains abstract filesystem credentials
     """
     partition_info_pointer = paths.get_partition_info_pointer(catalog_base_dir)
@@ -109,14 +111,7 @@ def write_partition_info(
     data_frame["Dir"] = [int(x / 10_000) * 10_000 for x in data_frame["Npix"]]
 
     # Reorder the columns to match full path, and force to integer types.
-    data_frame = data_frame[
-        [
-            "Norder",
-            "Dir",
-            "Npix",
-            "num_rows",
-        ]
-    ].astype(int)
+    data_frame = data_frame[["Norder", "Dir", "Npix", "num_rows"]].astype(int)
 
     file_io.write_dataframe_to_csv(
         data_frame, partition_info_pointer, index=False, storage_options=storage_options

src/hipscat/pixel_math/margin_bounding.py

@@ -30,8 +30,8 @@ def check_margin_bounds(r_asc, dec, pixel_order, pixel, margin_threshold, step=1
             memory issues.
     Returns:
         :obj:`numpy.array` of boolean values corresponding to the ra and dec
-            coordinates checked against whether a given point is within any of the
-            provided polygons.
+        coordinates checked against whether a given point is within any of the
+        provided polygons.
     """
     num_points = len(r_asc)
     if num_points != len(dec):

src/hipscat/pixel_math/pixel_margins.py

@@ -27,17 +27,18 @@ def get_edge(d_order, pix, edge):
         dk (int): the change in k that we wish to find the margins for.
         pix (int): the healpix pixel to find margin pixels of.
         edge (int): the edge we want to find for the given pixel. (0-7)
-            0: NE edge
-            1: E corner
-            2: SE edge
-            3: S corner
-            4: SW edge
-            5: W corner
-            6: NW edge
-            7: N corner
+
+            - 0: NE edge
+            - 1: E corner
+            - 2: SE edge
+            - 3: S corner
+            - 4: SW edge
+            - 5: W corner
+            - 6: NW edge
+            - 7: N corner
     Returns:
         one-dimensional numpy array of long integers, filled with the healpix pixels
-            at order kk+dk that border the given edge of pix.
+        at order kk+dk that border the given edge of pix.
     """
     if edge < 0 or edge > 7:
         raise ValueError("edge can only be values between 0 and 7 (see docstring)")
@@ -74,7 +75,7 @@ def get_margin(order, pix, d_order):
             Must be greater than kk.
     Returns:
         one-dimensional numpy array of long integers, filled with the healpix pixels
-            at order kk+dk that border pix.
+        at order kk+dk that border pix.
     """
     if d_order < 1:
         raise ValueError("dk must be greater than order")
@@ -122,8 +123,8 @@ def pixel_is_polar(order, pix):
         pix (int): the id of a healpixel to be checked. must be in the nested id scheme.
     Returns:
         tuple of a boolean and a string, the boolean indicating whether the pixel
-            polar and the string denoting which pole it is ('North' or 'South')).
-            string is empty in the case that the pixel isn't polar.
+        polar and the string denoting which pole it is ('North' or 'South')).
+        string is empty in the case that the pixel isn't polar.
     """
     nside = hp.order2nside(order)
     npix = hp.nside2npix(nside)

src/hipscat/pixel_math/validators.py

@@ -24,7 +24,7 @@ def validate_radius(radius_arcsec: float):
         radius_arcsec (float): The cone radius, in arcseconds
 
     Raises:
-        ValueError if radius is non-positive
+        ValueError: if radius is non-positive
     """
     if radius_arcsec <= 0:
         raise ValueError(ValidatorsErrors.INVALID_RADIUS.value)
@@ -37,7 +37,7 @@ def validate_declination_values(dec: float | List[float]):
         dec (float | List[float]): The declination values to be validated
 
     Raises:
-        ValueError if declination values are not in the [-90,90] degree range
+        ValueError: if declination values are not in the [-90,90] degree range
     """
     dec_values = np.array(dec)
     lower_bound, upper_bound = -90.0, 90.0
@@ -53,7 +53,7 @@ def validate_polygon(vertices: np.ndarray):
         vertices (np.ndarray): The polygon vertices, in cartesian coordinates
 
     Raises:
-        ValueError exception if the polygon is invalid.
+        ValueError: exception if the polygon is invalid.
     """
     if len(vertices) < 3:
         raise ValueError(ValidatorsErrors.INVALID_NUM_VERTICES.value)