Improve TestCase note example

docs/changelog.rst

@@ -3,6 +3,8 @@ Changelog
 =========
 
 * :release:`0.12.3 <2023-12-20>`
+* :support:`117` Improve the ``TestCase`` docstring example for notes about
+  unexpected external data changes
 * :bug:`128` Properly handle assertion failures during setUp/tearDown
 * :support:`145` Support Python 3.12 (and drop 3.8)
 * :release:`0.12.2 <2023-12-20>`

docs/examples/catalog_data.py

@@ -0,0 +1,17 @@
+import requests
+import marbles.core
+
+
+class CatalogTestCase(marbles.core.TestCase):
+
+    def test_product_count(self):
+        endpoint = 'https://example.com/api/v1/products'
+        products = requests.get(endpoint).json()
+
+        self.assertGreaterEqual(
+            len(products),
+            100,
+            note=('The upstream catalog normally contains at least 100 '
+                  'products. A lower count may indicate an incomplete '
+                  'data refresh.')
+        )

marbles/core/marbles/core/marbles.py

@@ -525,8 +525,7 @@ class TestCase(unittest.TestCase):
 
     Example:
 
-    .. literalinclude:: examples/getting_started.py.annotated
-       :lines: 1-4,33-44
+    .. literalinclude:: examples/catalog_data.py
     '''
 
     failureException = ContextualAssertionError