Merge pull request #16 from cnerg/numpy_docs

Author: gonuke

acme_corp/do_task.py

@@ -4,20 +4,26 @@
 
 logger = logging.getLogger(__name__)
 
-# using Sphinx docstrings style: <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>
+# using numpy style docstrings style: <https://numpydoc.readthedocs.io/en/stable/format.html>
 
 def perform_action(args, input_data):
     """Perform some action
 
     Following the principle of separation of concerns, this method only
     performs the action, but does not have any input or output.
 
-    :param args: argparse object with many possible members based on argparse configuration
-    :type args: argparse.ArgumentParser
-    :param input_data: dictionary of input data read from YAML file
-    :type input_data: dict
-    :returns: string that describes the input quantities
-    :rtype: str
+    Parameters
+    ----------
+    args : argparse.ArgumentParser
+        argparse object with many possible members based on argparse
+        configuration
+    input_data : dict
+        dictionary of input data read from YAML file
+
+    Returns
+    -------
+    str
+        string that describes the input quantities
     """
 
     return f"Some results based on args:\n{args}\n and input_data:\n{input_data}\n"
@@ -29,12 +35,18 @@ def report_results(args, input_data, results):
     Following the principle of separation of concerns, this method only
     performs output and does not do any actions.
 
-    :param args: argparse object with many possible members based on argparse configuration
-    :type args: argparse.ArgumentParser
-    :param input_data: dictionary of input data read from YAML file
-    :type input_data: dict
+    Parameters
+    ----------
+    args : argparse.ArgumentParser
+        argparse object with many possible members based on argparse
+        configuration
+    input_data : dict
+        dictionary of input data read from YAML file
 
-    :returns: None
+    Returns
+    -------
+    unknown
+        None
     """
 
     logger.info(
@@ -50,8 +62,10 @@ def task_args():
     `filename` : required positional argument
     `verbose` : optional keyword argument
 
-    :returns: argparse object with various members depending on configuration
-    :rtype: argparse.ArgumentParser
+    Returns
+    -------
+    argparse.ArgumentParser
+        argparse object with various members depending on configuration
     """
 
     parser = argparse.ArgumentParser(
@@ -75,10 +89,17 @@ def read_input(input_filename):
 
     inputs
     -------
-    :param input_filename: a string with a filename/path accessible from the current location
-    :type input_filename: str
-    :returns: the data from the YAML file.
-    :rtype: dict
+
+    Parameters
+    ----------
+    input_filename : str
+        a string with a filename/path accessible from the current
+        location
+
+    Returns
+    -------
+    dict
+        the data from the YAML file.
     """
 
     with open(input_filename, "r") as yaml_file:

acme_corp/piano.py

@@ -1,13 +1,13 @@
 class Piano:
-    """
-    A grand piano proudly built by ACME corporation.
+    """A grand piano proudly built by ACME corporation.
 
     Weighing half a ton be careful when hoisting this precariously over
     sidewalks.
 
-    .. warning::
-        Always use proper rigging techniques when hoisting this above
-        above any paths that may be occupied by any Road Runners.
+    Warnings
+    --------
+    Always use proper rigging techniques when hoisting this above
+    above any paths that may be occupied any Road Runners.
     """
 
     def __init__(self):
@@ -23,20 +23,22 @@ def drop(self):
 
     @property
     def weight(self):
-        """
-        The current weight of the piano.
+        """The current weight of the piano.
 
-        :returns: the current weight.
-        :rtype: float
+        Returns
+        -------
+        float
+            the current weight.
         """
         return self._weight
 
     @property
     def height(self):
-        """
-        The current height of the piano.
+        """The current height of the piano.
 
-        :returns: the current height.
-        :rtype: float
+        Returns
+        -------
+        float
+            the current height.
         """
         return self._height