Integrate docs pages from NSLS-II guide

docs/pages/developers/refraction.py

@@ -0,0 +1,32 @@
+# example/refraction.py
+
+import numpy as np
+
+
+def snell(theta_inc, n1, n2):
+    """
+    Compute the refraction angle using Snell's Law.
+
+    See https://en.wikipedia.org/wiki/Snell%27s_law
+
+    Parameters
+    ----------
+    theta_inc : float
+        Incident angle in radians.
+    n1, n2 : float
+        The refractive index of medium of origin and destination medium.
+
+    Returns
+    -------
+    theta : float
+        refraction angle
+
+    Examples
+    --------
+    A ray enters an air--water boundary at pi/4 radians (45 degrees).
+    Compute exit angle.
+
+    >>> snell(np.pi/4, 1.00, 1.33)
+    0.5605584137424605
+    """
+    return np.arcsin(n1 / n2 * np.sin(theta_inc))

docs/pages/developers/test_examples.py

@@ -0,0 +1,26 @@
+# example/tests/test_examples.py
+
+import numpy as np
+from ..refraction import snell
+# (The above is equivalent to `from example.refraction import snell`.
+# Read on for why.)
+
+
+def test_perpendicular():
+    # For any indexes, a ray normal to the surface should not bend.
+    # We'll try a couple different combinations of indexes....
+
+    actual = snell(0, 2.00, 3.00)
+    expected = 0
+    assert actual == expected
+
+    actual = snell(0, 3.00, 2.00)
+    expected = 0
+    assert actual == expected
+
+
+def test_air_water():
+    n_air, n_water = 1.00, 1.33
+    actual = snell(np.pi/4, n_air, n_water)
+    expected = 0.5605584137424605
+    assert np.allclose(actual, expected)