cleaned up and automated the examples page.

Author: ChrisBarker-NOAA

.github/workflows/conda_test.yml

@@ -1,4 +1,4 @@
-name: Run tests with miniconda
+name: Run tests with miniforge
 on: [push]
 
 jobs:
@@ -36,6 +36,11 @@ jobs:
         run: |
             pytest --pyargs py_gd
 
+      - name: Test Examples
+        shell: bash -l {0}
+        run: |
+            python docs/examples/run_all_examples.py
+
   lint:
     name: Flake8 linting
     runs-on: "ubuntu-latest"

.gitignore

@@ -1,7 +1,8 @@
 #specific to this repo:
 
 py_gd/py_gd.c
-docs/examples/Mandelbrot.png
+docs/examples/*.png
+docs/examples/*.gif
 
 
 # mac files

docs/examples/ultra_simple.py docs/examples/0-ultra_simple.pydocs/examples/ultra_simple.py renamed to docs/examples/0-ultra_simple.py

@@ -1,5 +1,5 @@
 """
-ultra_simple_example.py
+Ultra Simple Example
 
 About the simplest example for py_gd
 
@@ -12,5 +12,5 @@
 
 img.draw_line((1, 1), (400, 300), color='red', line_width=10)
 
-img.save('ultra_simple.png', 'png')
+img.save('0-ultra_simple.png', 'png')
 

docs/examples/build_example_page.py

@@ -0,0 +1,51 @@
+
+from pathlib import Path
+
+HERE = Path(__file__).parent
+
+HEADER = """.. _sample_scripts:
+
+Sample Scripts
+==============
+
+A good way to learn to use py_gd is to check out a few example scripts.
+
+"""
+
+all_examples = [fn for fn in HERE.glob("*.py") if not fn.name in {"build_color_images.py",
+                                                                  "run_all_examples.py",
+                                                                  "build_example_page.py"}
+                                                                  ]
+
+def gen_example(script_path):
+    if "draw_dots" in str(script_path.stem):
+        img_filename = str(script_path.stem) + ".gif"
+    else:
+        img_filename = str(script_path.stem) + ".png"
+
+    docstring = []
+    with open(script_path) as script:
+        # find the docstring
+        for line in script:
+            if line.startswith('"""'):
+                break
+        for line in script:
+            line = line.strip()
+            if line.startswith('"""'):
+                break
+            else:
+                docstring.append(line)
+    section = f"""
+
+{docstring[0]}\n{"-"*len(docstring[0])}
+{"\n".join(docstring[1:])}
+
+.. image:: examples/{img_filename}
+    :align: center
+    """
+    return section
+
+with open(HERE / "../sample_scripts.rst", 'w') as rst:
+    rst.write(HEADER)
+    for script in all_examples:
+        rst.write(gen_example(script))

docs/examples/colorramp.py

@@ -1,9 +1,9 @@
 """
-colorramp.py
+Using a Color Ramp
 
 Example of how to use a colorramp
 
-IN this case, we plot a "Heatmap" of a surface from the equation:
+In this case, we plot a "Heatmap" of a surface from the equation:
 
 z = sin(x) + sin(y)
 """

docs/examples/draw_dots.py

@@ -1,5 +1,5 @@
 """
-draw_dots.py
+Animation Example
 
 
 This draws a bunch of dots in different colors
@@ -26,11 +26,11 @@
 img.draw_dots(points, diameter=10, color=colors)
 
 #  Save the first frame as a PNG
-img.save('dots.png', 'png')
+img.save('draw_dots.png', 'png')
 
 
 # create the animation
-anim = Animation('dots.gif',
+anim = Animation('draw_dots.gif',
                  delay=10,  # in 1/100s
                  )
 

docs/examples/mandelbrot.py

@@ -1,7 +1,7 @@
 """
-Using py_gd to draw a Madelbrot set
+Drawing a Madelbrot set
 
-This sets the colors pixel by pixel
+Draws a Madelbrot by setting colors pixel by pixel
 """
 
 import numpy as np

docs/examples/moderate_complex.py

@@ -1,15 +1,18 @@
 """
+Example with Moderate Complexity
+
 py_gd demo with moderate complexity -- showing a number of the features
 
-CAn you tell what's being drawn without looking at the results?
+Can you tell what's being drawn from the code without looking at the results?
 
 """
 
 # Everything you need is in the Image object
+from py_gd import Image
 
+# Need some math ...
 from math import sin, cos, radians
 
-from py_gd import Image
 
 img = Image(width=800, height=600, preset_colors='xkcd')
 

docs/examples/run_all_examples.py

@@ -12,12 +12,11 @@
 
 HERE = Path(__file__).parent
 
-def not_example(path):
-    return path.name in {"build_color_images.py",
-                         "run_all_examples.py"}
 
 all_examples = [fn for fn in HERE.glob("*.py") if not fn.name in {"build_color_images.py",
-                                                                    "run_all_examples.py"}]
+                                                                  "run_all_examples.py",
+                                                                  "build_example_page.py"}
+                                                                  ]
 
 failures = 0
 for script in all_examples:

docs/examples/draw_star.py docs/examples/spline_star.pydocs/examples/draw_star.py renamed to docs/examples/spline_star.py

@@ -1,5 +1,10 @@
 """
-Drawing a star with a spline
+Smooth Polygon
+
+This example draws a star with rounded points, with varying roundedness.
+
+It uses a "Spline Polygon:
+
 """
 
 import numpy as np