update testing/docs

Author: d-chambers

modules/documentation/overview.qmd

@@ -10,13 +10,14 @@ Don't document the program; program the document.
 :::
 
 # Documentation
-Documenting all software is important, but just like testing, selecting the appropriate depends on the type of software
-and audience. For example, a simple script for producing a figure for a report will be documented very differently from
-an open-source library used by 1000s of people. Its not a coincidence that some of the most popular python packages are
-also the best documented. However, its not the *volume* of documentation that counts, but *quality*.
-
-Types of documentation include code comments, docstrings, tutorials, how tos, quickstarts, references, etc. Each one
-has its place, and we will touch discuss them.
+Documenting all software is important, but just like testing, selecting the appropriate level and strategy
+depends on the type of software its audience. For example, a simple script for producing a figure for a 
+report will be documented very differently from a popular open-source library. It's not a coincidence 
+that some of the most popular python packages are also the best documented. 
+However, it's not the *volume* of documentation that counts, but *quality*.
+
+Types of documentation include code comments, docstrings, readmes, tutorials, how tos, quickstarts, references, etc. 
+Each one has its place.
 
 # Objectives
 

modules/documentation/slides.qmd

@@ -21,14 +21,13 @@ footer: \
 
 
 # What is it? 
-<br>
 
 Documentation is:
 
 :::{.incremental}
 - User's manual
 - Blueprints
-- Promotional material
+- Advertisements
 - Sticky notes
 - Textbook
 - Prose
@@ -44,7 +43,7 @@ Documentation is:
 - Code comments (in-line, block)
 - Docstrings
 - Readme
-- Project Documentation
+- Project documentation
 :::
 
 
@@ -72,7 +71,7 @@ Use sparingly. Explain why, not what.
 <br>
 
 ```python
-extent = width + 1  # Add a bit to width  
+extent = width + 1  # add one to width  
 ```
 
 
@@ -343,9 +342,9 @@ pytest --doctest-modules
 :::{.incremental}
 - Use a spell checker
 - Use complete sentences
-- Try to be empathetic
+- Try to be empathic, try to be a friend
 - It's fine if the docstring is longer than the code
-- Typehints are good too, don't be redundant.
+- Typehints are good too, don't be redundant
 :::
 
 
@@ -371,11 +370,14 @@ def my_func(thing_a, thing_b):
 
 Your project's elevator pitch / note in a bottle
 
+:::{.fragment}
+
 - Short
 - Show code snippets
 - Describe basic functionality
 - A prospective user knows within 2 minutes if the library might solve their problem
 
+:::
 
 
 # Markdown/reST

modules/testing/overview.qmd

@@ -45,7 +45,7 @@ Here we simply try to highlight some of the main ideas and provide the basics of
 
 In this module, we will cover:
 
-1. Prevalent testing taxonomies and common types of testing
+1. Software testing approaches and domains
 2. Basics of the pytest framework
 
 # Reading

modules/testing/slides.qmd

@@ -523,14 +523,14 @@ import matplotlib.pyplot as plt
 import numpy as np
 
 with plt.xkcd():
-    x = np.arange(1000)
+    x = np.arange(100)
     
-    y = np.sqrt(x)
+    y = np.log10(x)
     
     plt.plot(x, y)
     
-    plt.xlabel("Time")
-    plt.ylabel("Benefit")
+    plt.xlabel("Testing Efforts")
+    plt.ylabel("Quality Improvements")
     plt.xticks([])
     plt.yticks([])
 plt.show()
@@ -876,7 +876,7 @@ def test_data_2(data):
 
 # Pytest Marks
 
-```{.python code-line-numbers="1||3-4|7-8|11-12"}
+```{.python code-line-numbers="1||3-4|7-8|11-12|15-16"}
 import pytest
     
 @pytest.mark.slow
@@ -887,6 +887,10 @@ def test_make_new_friends():
 def test_gaze_into_the_abyss():
     ...
     
+@pytest.mark.skipif(on_windows, reason="windows sucks")
+def test_do_useful_things():
+    ...
+    
 @pytest.mark.xfail
 def test_impress_my_father():
     ...
@@ -896,6 +900,8 @@ def test_impress_my_father():
 
 # Pytest Marks
 
+<br>
+
 ```python
 import pytest
 
@@ -942,7 +948,7 @@ pytest -m "slow not webtests"
 - Fixtures should be as close to tests as possible
 - Move fixtures from classes, to modules, to conftest.py
 - Each python file (x.py) should have a test file (test_x.py)
-- Test files mirror packages org. in tests/ directory
+- Test files mirror package org. in tests/ directory
 :::