improve docstrings for future comptability with mkdocs

src/pg_rad/isotope.py

@@ -1,18 +1,17 @@
 class Isotope:
+    """Represents the essential information of an isotope.
+
+    Args:
+        name (str): Full name (e.g. Caesium-137).
+        E (float): Energy of the primary gamma in keV.
+        b (float): Branching ratio for the gamma at energy E.
+    """  
     def __init__(
             self,
             name: str,
             E: float,
             b: float
-    ):
+    ):        
-        """_Represents the essential information of an isotope._
-
-        Args:
-            name (str): Full name (e.g. Caesium-137).
-            E (float): Energy of the primary gamma in keV.
-            b (float): Branching ratio for the gamma at energy E.
-        """        
-        
         if E <= 0:
             raise ValueError("primary_gamma must be a positive energy (keV).")
 

src/pg_rad/landscape.py

@@ -6,20 +6,19 @@ from pg_rad.path import Path
 from pg_rad.objects import Source
 
 class Landscape:
+    """A generic Landscape that can contain a Path and sources.
+
+    Args:
+        air_density (float, optional): Air density in kg / m^3. Defaults to 1.243.
+        size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500.
+        scale (str, optional): The scale of the size argument passed. Defaults to 'meters'.
+    """    
     def __init__(
             self,
             air_density: float = 1.243,
             size: int | tuple[int, int, int] = 500,
             scale = 'meters',
-            ):
+            ):    
-        """_A generic Landscape that can contain a Path and sources._
-
-        Args:
-            air_density (float, optional): Air density in kg / m^3. Defaults to 1.243.
-            size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500.
-            scale (str, optional): The scale of the size argument passed. Defaults to 'meters'.
-        """        
-        
         if isinstance(size, int):
             self.world = np.zeros((size, size, size))
         elif isinstance(size, tuple) and len(size) == 3:
@@ -34,7 +33,7 @@ class Landscape:
         self.sources: list[Source] = []
     
     def plot(self, z = 0):
-        """_Plot a slice of the world at a height z._
+        """Plot a slice of the world at a height `z`.
 
         Args:
             z (int, optional): Height of slice. Defaults to 0.
@@ -78,7 +77,14 @@ class Landscape:
         return fig, ax
 
     def add_sources(self, *sources: Source):
-        """Add one or more point sources to the world."""
+        """Add one or more point sources to the world.
+
+        Args:
+            *sources (pg_rad.objects.Source): One or more sources, passed as
+            Source1, Source2, ...
+        Raises:
+            ValueError: If the source is outside the boundaries of the landscape.
+        """        
 
         max_x, max_y, max_z = self.world.shape[:3]
 
@@ -88,23 +94,26 @@ class Landscape:
                  0 <= source.z < max_z)
             for source in sources
         ):
-            raise ValueError("One or more sources are outside the world boundaries.")
+            raise ValueError("One or more sources are outside the landscape!")
 
         self.sources.extend(sources)
 
     def set_path(self, path: Path):
+        """
+        Set the path in the landscape.
+        """
         self.path = path
     
 def create_landscape_from_path(path: Path, max_z = 500):
-    """_Generate a Landscape from a path, using its dimensions to determine
+    """Generate a landscape from a path, using its dimensions to determine
-    the size of the Landscape._
+    the size of the landscape.
 
     Args:
         path (Path): A Path object describing the trajectory.
         max_z (int, optional): Height of the world. Defaults to 500 meters.
 
     Returns:
-        Landscape: A Landscape with dimensions based on the provided Path.
+        landscape (pg_rad.landscape.Landscape): A landscape with dimensions based on the provided Path.
     """    
     max_x = np.ceil(max(path.x_list))
     max_y = np.ceil(max(path.y_list))

src/pg_rad/objects.py

@@ -11,6 +11,16 @@ class Object:
             z: float,
             name: str = "Unnamed object",
             color: str = 'grey'):
+        """
+        A generic object.
+
+        Args:
+            x (float): X coordinate.
+            y (float): Y coordinate.
+            z (float): Z coordinate.
+            name (str, optional): Name for the object. Defaults to "Unnamed object".
+            color (str, optional): Matplotlib compatible color string. Defaults to "red".
+        """
         
         self.x = x
         self.y = y
@@ -35,7 +45,7 @@ class Source(Object):
             isotope: Isotope,
             name: str | None = None,
             color: str = "red"):
-        """_A point source._
+        """A point source.
 
         Args:
             x (float): X coordinate.
@@ -47,7 +57,8 @@ class Source(Object):
             Defaults to None, making the name sequential.
             (Source-1, Source-2, etc.).
             color (str, optional): Matplotlib compatible color string. Defaults to "red".
-        """        
+        """
+        
         self.id = Source._id_counter
         Source._id_counter += 1
 

src/pg_rad/path.py

@@ -13,11 +13,11 @@ logger = setup_logger(__name__)
 
 class PathSegment:
     def __init__(self, a: tuple[float, float], b: tuple[float, float]):
-        """_A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b)._
+        """A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b).
 
         Args:
-            a (tuple[float, float]): _The starting point (x_a, y_a)._
+            a (tuple[float, float]): The starting point (x_a, y_a).
-            b (tuple[float, float]): _The final point (x_b, y_b)._
+            b (tuple[float, float]): The final point (x_b, y_b).
         """        
         self.a = a
         self.b = b
@@ -45,7 +45,7 @@ class Path:
             z: float = 0,
             simplify_path = False
                  ):
-        """_Construct a path of sequences based on a list of coordinates._
+        """Construct a path of sequences based on a list of coordinates.
 
         Args:
             coord_list (Sequence[tuple[float, float]]): List of x,y coordinates.
@@ -95,7 +95,7 @@ def piecewise_regression_on_path(
         keep_endpoints_equal: bool = False,
         n_breakpoints: int = 3
         ):
-    """_Take a Path object and return a piece-wise linear approximated Path._
+    """From full resolution x and y arrays, return a piecewise linearly approximated/simplified pair of x and y arrays.
 
     This function uses the `piecewise_regression` package. From a full set of
     coordinate pairs, the function fits linear sections, automatically finding
@@ -119,8 +119,11 @@ def piecewise_regression_on_path(
         n_breakpoints (int, optional): Number of breakpoints. Defaults to 3.
 
     Returns:
-        x (Sequence[float]): _Reduced list of x coordinates._
+        x (list[float]): Reduced list of x coordinates.
-        y (Sequence[float]): _Reduced list of y coordinates._
+        y (list[float]): Reduced list of y coordinates.
+
+    Raises:
+        ConvergenceError: If the fitting algorithm failed to simplify the path.
 
     Reference:
         Pilgrim, C., (2021). piecewise-regression (aka segmented regression) in Python. Journal of Open Source Software, 6(68), 3859, https://doi.org/10.21105/joss.03859.
@@ -163,11 +166,10 @@ def path_from_RT90(
         north_col: str = "North",
         **kwargs
         ) -> Path:
-    
+    """Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame.
-    """_Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame._
 
     Args:
-        df (pd.DataFrame): DataFrame containing at least the two columns noted in the cols argument.
+        df (pandas.DataFrame): DataFrame containing at least the two columns noted in the cols argument.
         east_col (str): The column name for the East coordinates.
         north_col (str): The column name for the North coordinates.