Convert general submodule docstrings to numpydoc (#53)

* convert general submodule docstrings to numpydoc

* update docstring of is_even

brainglobe_utils/general/exceptions.py

@@ -2,9 +2,10 @@ class CommandLineInputError(Exception):
     """Exception raised for incorrect or illogical command line inputs that
     are not caught elsewhere.
 
-    Attributes:
-        expression -- input expression in which the error occurred
-        message -- explanation of the error
+    Attributes
+    ----------
+        message : str
+            explanation of the error
     """
 
     def __init__(self, message):

brainglobe_utils/general/list.py

@@ -4,8 +4,16 @@
 def remove_empty_string(str_list):
     """
     Removes any empty strings from a list of strings
-    :param str_list: List of strings
-    :return: List of strings without the empty strings
+
+    Parameters
+    ----------
+    str_list : list of str
+        List of strings.
+
+    Returns
+    -------
+    list of str
+        List of strings without the empty strings.
     """
     return list(filter(None, str_list))
 
@@ -17,11 +25,23 @@ def unique_elements_lists(list_in):
 
 def check_unique_list(in_list, natural_sort=True):
     """
-    Checks if all the items in a list are unique or not
-    :param list in_list: Input list
-    :param bool natural_sort: Sort the resulting items naturally
-    (default: True)
-    :return: True/False and a list of any repeated values
+    Checks if all the items in a list are unique or not.
+
+    Parameters
+    ----------
+    in_list : list
+        Input list.
+
+    natural_sort : bool, optional
+        Sort the resulting items naturally. Default is True.
+
+    Returns
+    -------
+    bool
+        True if all items are unique, False otherwise.
+
+    list
+        A list of any repeated values.
     """
     unique = set(in_list)
     repeated_items = []
@@ -43,11 +63,25 @@ def common_member(a, b, natural_sort=True):
     """
     Checks if two lists (or sets) have a common member, and if so, returns
     the common members.
-    :param a: First list (or set)
-    :param b: Second list (or set)
-    :param bool natural_sort: Sort the resulting items naturally
-    (default: True)
-    :return: True/False and the list of values
+
+    Parameters
+    ----------
+    a : list or set
+        First list (or set).
+
+    b : list or set
+        Second list (or set).
+
+    natural_sort : bool, optional
+        Sort the resulting items naturally. Default is True.
+
+    Returns
+    -------
+    bool
+        True if common members exist, False otherwise.
+
+    list
+        The list of common values.
     """
     a_set = set(a)
     b_set = set(b)

brainglobe_utils/general/numerical.py

@@ -3,9 +3,22 @@
 
 def is_even(num):
     """
-    Returns True if a number is even
-    :param num:
-    :return:
+    Returns True if the non-zero input number is even.
+
+    Parameters
+    ----------
+    num : int
+        Input number.
+
+    Returns
+    -------
+    bool
+        True if number is even, otherwise False.
+
+    Raises
+    ------
+    NotImplementedError
+        If the input number is zero.
     """
     if num == 0:
         raise NotImplementedError(
@@ -20,11 +33,26 @@ def is_even(num):
 
 def check_positive_float(value, none_allowed=True):
     """
-    Used in argparse to enforce positive floats
-    FromL https://stackoverflow.com/questions/14117415
-    :param value: Input value
-    :param none_allowed: If false, throw an error for None values
-    :return: Input value, if it's positive
+    Used in argparse to enforce positive floats.
+    Source: https://stackoverflow.com/questions/14117415
+
+    Parameters
+    ----------
+    value : float
+        Input value.
+
+    none_allowed : bool, optional
+        If False, throw an error for None values.
+
+    Returns
+    -------
+    float
+        Input value, if it's positive.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If input value is invalid.
     """
     ivalue = value
     if ivalue is not None:
@@ -42,11 +70,26 @@ def check_positive_float(value, none_allowed=True):
 
 def check_positive_int(value, none_allowed=True):
     """
-    Used in argparse to enforce positive ints
-    FromL https://stackoverflow.com/questions/14117415
-    :param value: Input value
-    :param none_allowed: If false, throw an error for None values
-    :return: Input value, if it's positive
+    Used in argparse to enforce positive ints.
+    Source: https://stackoverflow.com/questions/14117415
+
+    Parameters
+    ----------
+    value : int
+        Input value.
+
+    none_allowed : bool, optional
+        If False, throw an error for None values.
+
+    Returns
+    -------
+    int
+        Input value, if it's positive.
+
+    Raises
+    ------
+    argparse.ArgumentTypeError
+        If input value is invalid.
     """
     ivalue = value
     if ivalue is not None:

brainglobe_utils/general/pathlib.py

@@ -1,8 +1,18 @@
 def append_to_pathlib_stem(path, string_to_append):
     """
-    Appends a string to the stem of a pathlib object
-    :param path: pathlib path
-    :param string_to_append:  string to append to the stem
-    :return: pathlib object with the string added to the stem
+    Appends a string to the stem of a pathlib object.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        Pathlib path.
+
+    string_to_append : str
+        String to append to the stem.
+
+    Returns
+    -------
+    pathlib.Path
+        Pathlib object with the string added to the stem.
     """
     return path.parent / (path.stem + string_to_append + path.suffix)

brainglobe_utils/general/string.py

@@ -12,15 +12,32 @@ def get_text_lines(
     encoding="utf8",
 ):
     """
-    Return only the nth line of a text file
-    :param file: Any text file
-    :param return_lines: Which specific line/lines to read
-    :param rstrip: Remove trailing characters
-    :param sort: If true, naturally sort the data
-    :param remove_empty_lines: If True, ignore empty lines
-    :param encoding: What encoding the text file has.
-    Default: None (platform dependent)
-    :return: The nth line
+    Return only the nth line of a text file.
+
+    Parameters
+    ----------
+    file : str or pathlib.Path
+        Path to any text file.
+
+    return_lines : int, optional
+        Which specific line to read.
+
+    rstrip : bool, optional
+        Whether to remove trailing characters.
+
+    sort : bool, optional
+        If True, naturally sort the data.
+
+    remove_empty_lines : bool, optional
+        If True, ignore empty lines.
+
+    encoding : str, optional
+        What encoding the text file has.
+
+    Returns
+    -------
+    str or list of str
+        The nth line or lines.
     """
     with open(file, encoding=encoding) as f:
         lines = f.readlines()