update text for docs_and_testing.ipynb

Author: gantian127

lessons/python/docs_and_testing.ipynb

@@ -25,7 +25,7 @@
     "\n",
     "**Unit testing** is a coding practice where tests are written to verify that your functions and classes work as intended. It helps ensure that your code behaves correctly across different scenarios and makes it easier to detect and fix bugs.\n",
     "\n",
-    "In this tutorial, we will learn how to write documentation and unit tests for a function that calculates snowmelt, and practice these skills through hands-on exercises focused on a Diffusion Model class."
+    "In this tutorial, we will learn how to write documentation and unit tests for a function that calculates snowmelt and practice these skills through hands-on exercises focused on a Diffusion Model class."
    ]
   },
   {
@@ -57,11 +57,11 @@
     "\n",
     "4. API documentation\n",
     "\n",
-    "   Detailed descriptions of classes, functions, methods, and modules. It is typically generated using tools (e.g., [Sphinx](https://www.sphinx-doc.org/en/master/)) that extract information from docstrings written for the functions, classes, and modules. ([API doc example](https://landlab.readthedocs.io/en/v2.9.2/generated/api/landlab.components.overland_flow.generate_overland_flow_deAlmeida.html))\n",
+    "   Detailed descriptions of classes, functions, methods, and modules. It is typically generated using tools (e.g., [Sphinx](https://www.sphinx-doc.org/en/master/)) that extract information from docstrings written for the functions, classes, and modules. ([API documentation example](https://landlab.readthedocs.io/en/v2.9.2/generated/api/landlab.components.overland_flow.generate_overland_flow_deAlmeida.html))\n",
     "\n",
     "5. Tutorials and Examples\n",
     "\n",
-    "   Code examples, Jupyter notebooks, or step-by-step guides for using the software. ([Tutorial example](https://github.com/landlab/landlab/blob/master/docs/source/tutorials/boundary_conditions/set_BCs_on_raster_perimeter.ipynb))"
+    "   Code examples, Jupyter notebooks, or step-by-step guides for using the software. ([Tutorial example](https://landlab.readthedocs.io/en/v2.9.2/user_guide/overland_flow_user_guide.html))"
    ]
   },
   {
@@ -82,7 +82,7 @@
    "source": [
     "The example code below shows the calculate_snowmelt() function. Its documentation follows the NumPy-style docstring format, which is widely adopted by major scientific libraries such as NumPy, SciPy, and pandas. This style is especially common in scientific and data-analysis code.\n",
     "\n",
-    "In the documentation, the Examples section provides illustrative use cases of the function. These examples can also serve as the basis for unit tests, helping to verify that the function behaves as expected. We will discuss this further in a later section."
+    "In the documentation, the `Examples` section provides illustrative use cases of the function. These examples can also serve as the basis for unit tests, helping to verify that the function behaves as expected. We will discuss this further in the unit testing section."
    ]
   },
   {
@@ -99,7 +99,7 @@
     "    Parameters\n",
     "    ----------\n",
     "    temp : float\n",
-    "        Daily average temperature in Celsius.\n",
+    "        Daily average temperature in °C.\n",
     "    degree_day_factor : float\n",
     "        Melt factor in mm/°C/day.\n",
     "    days : int, optional\n",
@@ -140,8 +140,8 @@
    "id": "9",
    "metadata": {},
    "source": [
-    "### Frameworks for unit testing\n",
-    "Python offers several tools for writing and running tests. Three popular testing frameworks are doctest, unittest, and pytest. Each has its own strengths and is suited to different testing needs. - \n",
+    "### Tools for unit testing\n",
+    "Python offers several tools for writing and running tests. Three commonly used testing tools are doctest, unittest, and pytest. Each has its own strengths and is suited to different testing needs.\n",
     "- **doctest**: A standard Python library designed to test code examples embedded in docstrings. It is not a full-featured unit testing framework. But it’s ideal for verifying simple functions and ensuring that documentation remains accurate and executable.\n",
     "- **unittest**: A standard Python library that provides a framework for writing and running unit tests. It best suited for organizing larger test suites using test classes and methods.\n",
     "- **pytest**: A powerful third-party testing framework for writing and running tests. It is more flexible and powerful than unittest, supporting both standalone test functions and test classes. It also supports advanced features (e.g., parameterization, fixture) making it suitable for both simple and complex testing needs.\n",
@@ -157,8 +157,8 @@
     "We will use pytest to write the unit tests for the \"calculate_snowmelt( )\" function. Let's first think about what testing cases are needed for this function:\n",
     " - snowmelt occurs with valid input\n",
     " - no snowmelt with valid input\n",
-    " - invalide degree_day_factor input\n",
-    " - invalid day input"
+    " - invalid degree_day_factor input\n",
+    " - invalid days input"
    ]
   },
   {
@@ -178,9 +178,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import pytest\n",
-    "\n",
-    "\n",
     "# test snowmelt occurs\n",
     "def test_snowmelt_occurs():\n",
     "    \"\"\"Test that snowmelt occurs with valid input\"\"\"\n",
@@ -243,7 +240,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# test invalid day input"
+    "# test invalid days input"
    ]
   },
   {
@@ -280,15 +277,17 @@
     "If you know about [conda](https://docs.conda.io/projects/conda/en/stable/) and have installed it on your computer, you can follow the steps below to create the function file and the unit test file, and then create a conda environment for running the unit tests.\n",
     "\n",
     "1) Create a new folder named \"example\". Inside this folder, you’ll place your code and test files.\n",
-    "2) Create \"example.py\": paste the code for calculate_snowmelt() in this file.\n",
-    "3) Create \"test_example.py\": paste the unit test functions in this file. Remember to add oneline of code in this file:\n",
+    "2) Create \"example.py\": paste the code for calculate_snowmelt() function in this file.\n",
+    "3) Create \"test_example.py\": paste the four unit test functions in this file. Remember to add the code below in this file:\n",
     "```python\n",
+    "import pytest\n",
+    "\n",
     "from example import calculate_snowmelt\n",
     "```\n",
-    "4) Open a terminal, create a conda environment and activate it with the following commands. Remember to replace /path/to/your/diffusion with the actual path.\n",
+    "4) Open a terminal, create a conda environment and activate it with the following commands. Remember to replace /path/to/your/example_folder with the actual path.\n",
     "```bash\n",
-    "conda create -n unit_test pytest\n",
-    "conda activate unit_test\n",
+    "conda create -y -n unit_testing pytest\n",
+    "conda activate unit_testing\n",
     "cd /path/to/your/example_folder\n",
     "```"
    ]
@@ -320,7 +319,7 @@
     "```\n",
     "**doctest with incorrct example**\n",
     "```\n",
-    "$ python -m doctest example.py\n",
+    "$ python -m doctest example_wrong.py\n",
     "**********************************************************************\n",
     "File \"/Users/tiga7385/Desktop/course/example/example.py\", line 27, in ex\n",
     "ample.calculate_snowmelt\n",
@@ -684,7 +683,7 @@
     "    pass  # remove pass and add your code\n",
     "\n",
     "\n",
-    "# feel free to add additional test functions"
+    "# feel free to add additional unit test functions"
    ]
   },
   {
@@ -747,7 +746,7 @@
    "id": "34",
    "metadata": {},
    "source": [
-    "**3) Bonus Exercise: Run Unit Tests**\n",
+    "**3) Run Unit Tests**\n",
     "\n",
     "Follow the steps shown in the \"Run Unit Tests\" section to run the unit tests for the Diffution2D class on your computer. \n",
     "\n",