[Basics Concept Exercise]: Update docstrings and documents for guidos-gorgeous-lasagna

exercises/concept/guidos-gorgeous-lasagna/.docs/hints.md

@@ -38,6 +38,7 @@
 ## 5. Update the recipe with notes
 
 - Clearly [commenting][comments] and [documenting][docstrings] your code according to [PEP257][pep257] is always recommended.
+- Some examples of Google-style docstrings can be found in the Sphinx documentation for the [napoleon module][napoleon].
 
 [assignment]: https://docs.python.org/3/reference/simple_stmts.html#grammar-token-assignment-stmt
 [comments]: https://realpython.com/python-comments-guide/
@@ -46,6 +47,7 @@
 [docstrings]: https://docs.python.org/3/tutorial/controlflow.html#tut-docstrings
 [magic-numbers]: https://en.wikipedia.org/wiki/Magic_number_(programming)
 [naming]: https://realpython.com/python-variables/
+[napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#module-sphinx.ext.napoleon
 [numbers]: https://docs.python.org/3/tutorial/introduction.html#numbers
 [pep257]: https://www.python.org/dev/peps/pep-0257/
 [python as a calculator]: https://docs.python.org/3/tutorial/introduction.html#using-python-as-a-calculator

exercises/concept/guidos-gorgeous-lasagna/.docs/instructions.md

@@ -78,14 +78,18 @@ Go back through the recipe, adding "notes" in the form of [function docstrings][
 ```python
 def elapsed_time_in_minutes(number_of_layers, elapsed_bake_time):
     """Calculate the elapsed cooking time.
-
-    :param number_of_layers: int - the number of layers in the lasagna.
-    :param elapsed_bake_time: int - time the lasagna has been baking in the oven.
-    :return: int - total time elapsed (in minutes) preparing and baking.
+
+    Parameters:
+        number_of_layers (int): The number of layers in the lasagna.
+        elapsed_bake_time (int): Time the lasagna has been baking in the oven.
+
+    Returns:
+        int: The total time elapsed (in minutes) preparing and baking.
 
     This function takes two integers representing the number of lasagna 
     layers and the time already spent baking the lasagna. It calculates 
     the total elapsed minutes spent cooking (preparing + baking).
+
     """
 ```
 

exercises/concept/guidos-gorgeous-lasagna/.docs/introduction.md

@@ -209,13 +209,18 @@ Docstrings are declared using triple double quotes (""") indented at the same le
 
 ```python
 
-# An example from PEP257 of a multi-line docstring.
+# An example from PEP257 of a multi-line docstring
+# reformatted to use Google style non-type hinted docstrings.
+# Some additional details can be found in the Sphinx documentation:
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#getting-started
+
 def complex(real=0.0, imag=0.0):
     """Form a complex number.
 
-    Keyword arguments:
-    real -- the real part (default 0.0)
-    imag -- the imaginary part (default 0.0)
+    Keyword Arguments:
+        real (float): The real part of the number (default 0.0)
+        imag (float): The imaginary part of the number (default 0.0)
+
     """
 
     if imag == 0.0 and real == 0.0:
@@ -224,36 +229,45 @@ def complex(real=0.0, imag=0.0):
 ```
 
 
-Docstrings are read by automated documentation tools and are returned by calling the special attribute `.__doc__` on the function, method, or class name.
-Docstring conventions are laid out in [PEP257][pep257].
+Docstrings are read by automated documentation tools such as [Sphinx][sphinx] and are returned by calling the special attribute `.__doc__` on the function, method, or class name.
+General docstring conventions are laid out in [PEP257][pep257], but exact formats will vary by project and team.
+Exercism concept exercises try to follow the Google style for un-type hinted code.
 
 Docstrings can also function as [lightweight unit tests][doctests], which will be covered in a later exercise.
 
 
 ```python
 # An example on a user-defined function.
+# This uses Google style docstrings.
 >>> def raise_to_power(number, power):
-        """Raise a number to an arbitrary power.
-
-        :param number: int the base number.
-        :param power: int the power to raise the base number to.
-        :return: int - number raised to the specified power.
+    """Raise a number to an arbitrary power.
+
+    Parameters:
+        number (int): The base number.
+        power (int): The power to raise the base number to.
+
+    Returns:
+        int: The number raised to the specified power.
+
+    Takes a number and raises it to the specified power, returning the result.
 
-        Takes a number and raises it to the specified power, returning the result.
-        """
+    """
 
-        return number ** power
+    return number ** power
 ...
 
 # Calling the .__doc__ attribute of the function and printing the result.
 >>> print(raise_to_power.__doc__)
 Raise a number to an arbitrary power.
 
-    :param number: int the base number.
-    :param power: int the power to raise the base number to.
-    :return: int - number raised to the specified power.
+Parameters:
+    number (int): The base number.
+    power (int): The power to raise the base number to.
 
-    Takes a number and raises it to the specified power, returning the result.
+Returns:
+    int: The number raised to the specified power.
+
+Takes a number and raises it to the specified power, returning the result.
 ```
 
 [calls]: https://docs.python.org/3/reference/expressions.html#calls
@@ -271,4 +285,5 @@ Raise a number to an arbitrary power.
 [parameters]: https://docs.python.org/3/glossary.html#term-parameter
 [pep257]: https://www.python.org/dev/peps/pep-0257/
 [return]: https://docs.python.org/3/reference/simple_stmts.html#return
+[sphinx]: https://www.sphinx-doc.org/en/master/usage/index.html
 [type hints]: https://docs.python.org/3/library/typing.html

exercises/concept/guidos-gorgeous-lasagna/lasagna.py

@@ -8,15 +8,18 @@
 """
 
 
-#TODO: define your EXPECTED_BAKE_TIME (required) and PREPARATION_TIME (optional) constants below.
+#TODO (student): define your EXPECTED_BAKE_TIME (required) and PREPARATION_TIME (optional) constants below.
 
 
-#TODO: Remove 'pass' and complete the 'bake_time_remaining()' function below.
+#TODO (student): Remove 'pass' and complete the 'bake_time_remaining()' function below.
 def bake_time_remaining():
     """Calculate the bake time remaining.
 
-    :param elapsed_bake_time: int - baking time already elapsed.
-    :return: int - remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'.
+    Parameters:
+        elapsed_bake_time (int): The baking time already elapsed.
+
+    Returns:
+        int: The remaining bake time (in minutes) derived from 'EXPECTED_BAKE_TIME'.
 
     Function that takes the actual minutes the lasagna has been in the oven as
     an argument and returns how many minutes the lasagna still needs to bake
@@ -26,16 +29,16 @@ def bake_time_remaining():
     pass
 
 
-#TODO: Define the 'preparation_time_in_minutes()' function below.
+#TODO (student): Define the 'preparation_time_in_minutes()' function below.
 # To avoid the use of magic numbers (see: https://en.wikipedia.org/wiki/Magic_number_(programming)), you should define a PREPARATION_TIME constant.
 # You can do that on the line below the 'EXPECTED_BAKE_TIME' constant.
 # This will make it easier to do calculations, and make changes to your code.
 
 
 
-#TODO: define the 'elapsed_time_in_minutes()' function below.
+#TODO (student): define the 'elapsed_time_in_minutes()' function below.
 
 
 
-# TODO: Remember to go back and add docstrings to all your functions
+# TODO (student): Remember to go back and add docstrings to all your functions
 #  (you can copy and then alter the one from bake_time_remaining.)