Add XKCD comics to documentation

book/build.py

@@ -6,7 +6,9 @@ import urllib.parse
 SCRIPT_DIR = Path(__file__).parent.resolve()
 
 
-def generate_example(filename, title, strip_asserts=True, insert_run_link=True):
+def generate_example(
+    filename, title, strip_asserts=True, insert_run_link=True, footer=None
+):
     path_in = SCRIPT_DIR.parent / "examples" / f"{filename}.nbt"
     path_out = SCRIPT_DIR / "src" / f"example-{filename}.md"
     print(path_in)
@@ -33,6 +35,20 @@ def generate_example(filename, title, strip_asserts=True, insert_run_link=True):
         fout.writelines(code)
         fout.write("```\n")
 
+        if footer:
+            fout.write("\n")
+            fout.write(footer)
+            fout.write("\n")
+
+
+def xkcd_footer(number, img_name):
+    footer = '<p align="center" style="margin-top: 2em">'
+    footer += f'<a href="https://xkcd.com/{number}/"><img src="https://imgs.xkcd.com/comics/{img_name}.png" alt="XKCD {number}" style="max-width: 100%"></a>'
+    footer += f'<br>Source: <a href="https://xkcd.com/{number}/">https://xkcd.com/{number}/</a>'
+    footer += "</p>"
+
+    return footer
+
 
 generate_example("acidity", "Acidity")
 generate_example("barometric_formula", "Barometric formula")
@@ -46,10 +62,18 @@ generate_example("pipe_flow_rate", "Flow rate in a pipe")
 generate_example("population_growth", "Population growth")
 generate_example("recipe", "Recipe")
 generate_example("voyager", "Voyager")
-generate_example("xkcd_681", "XKCD 681", strip_asserts=False)
-generate_example("xkcd_687", "XKCD 687")
-generate_example("xkcd_2585", "XKCD 2585")
-generate_example("xkcd_2812", "XKCD 2812")
+generate_example(
+    "xkcd_681",
+    "XKCD 681",
+    footer=xkcd_footer(681, "gravity_wells"),
+)
+generate_example(
+    "xkcd_687", "XKCD 687", footer=xkcd_footer(687, "dimensional_analysis")
+)
+generate_example("xkcd_2585", "XKCD 2585", footer=xkcd_footer(2585, "rounding"))
+generate_example(
+    "xkcd_2812", "XKCD 2812", footer=xkcd_footer(2812, "solar_panel_placement")
+)
 
 generate_example(
     "numbat_syntax", "Syntax overview", strip_asserts=False, insert_run_link=False

book/src/example-xkcd_2585.md

@@ -37,3 +37,5 @@ ans -> mph           -> round
 print("I can ride my bike at {ans}.")
 print("If you round.")
 ```
+
+<p align="center" style="margin-top: 2em"><a href="https://xkcd.com/2585/"><img src="https://imgs.xkcd.com/comics/rounding.png" alt="XKCD 2585" style="max-width: 100%"></a><br>Source: <a href="https://xkcd.com/2585/">https://xkcd.com/2585/</a></p>

book/src/example-xkcd_2812.md

@@ -40,3 +40,5 @@ let savings_b = savings(sun_luminosity / sun_area)
 
 print(savings_b |> round)
 ```
+
+<p align="center" style="margin-top: 2em"><a href="https://xkcd.com/2812/"><img src="https://imgs.xkcd.com/comics/solar_panel_placement.png" alt="XKCD 2812" style="max-width: 100%"></a><br>Source: <a href="https://xkcd.com/2812/">https://xkcd.com/2812/</a></p>

book/src/example-xkcd_681.md

@@ -1,7 +1,7 @@
 <!-- This file is autogenerated! Do not modify it -->
 
 # XKCD 681
-<a href="https://numbat.dev/?q=%23+Gravity+wells%0A%23%0A%23+https%3A%2F%2Fxkcd.com%2F681%2F%0A%0Ause+extra%3A%3Aastronomy%0A%0Afn+well_depth%28mass%3A+Mass%2C+radius%3A+Length%29+-%3E+Length+%3D%0A++++G+%C3%97+mass+%2F+%28g0+%C3%97+radius%29+-%3E+km%0A%0Aassert_eq%28well_depth%28earth_mass%2C+earth_radius%29%2C+6379+km%2C+1+km%29%0Aassert_eq%28well_depth%28mars_mass%2C++mars_radius%29%2C++1286+km%2C+3+km%29%0Aassert_eq%28well_depth%28lunar_mass%2C+lunar_radius%29%2C++288+km%2C+1+km%29%0A"><i class="fa fa-play"></i> Run this example</a>
+<a href="https://numbat.dev/?q=%23+Gravity+wells%0A%23%0A%23+https%3A%2F%2Fxkcd.com%2F681%2F%0A%0Ause+extra%3A%3Aastronomy%0A%0Afn+well_depth%28mass%3A+Mass%2C+radius%3A+Length%29+-%3E+Length+%3D%0A++++G+%C3%97+mass+%2F+%28g0+%C3%97+radius%29+-%3E+km%0A%0Aprint%28%22Gravity+well+depths%3A%22%29%0Aprint%28%22Sun+++++%7Bwell_depth%28solar_mass%2C+solar_radius%29%3A8.0f%7D%22%29%0Aprint%28%22Earth+++%7Bwell_depth%28earth_mass%2C+earth_radius%29%3A8.0f%7D%22%29%0Aprint%28%22Moon++++%7Bwell_depth%28lunar_mass%2C+lunar_radius%29%3A8.0f%7D%22%29%0Aprint%28%22Mars++++%7Bwell_depth%28mars_mass%2C++mars_radius%29%3A8.0f%7D%22%29%0Aprint%28%22Jupiter+%7Bwell_depth%28jupiter_mass%2C+jupiter_radius%29%3A8.0f%7D%22%29%0A%0A"><i class="fa fa-play"></i> Run this example</a>
 
 ``` numbat
 # Gravity wells
@@ -13,7 +13,13 @@ use extra::astronomy
 fn well_depth(mass: Mass, radius: Length) -> Length =
     G × mass / (g0 × radius) -> km
 
-assert_eq(well_depth(earth_mass, earth_radius), 6379 km, 1 km)
-assert_eq(well_depth(mars_mass,  mars_radius),  1286 km, 3 km)
-assert_eq(well_depth(lunar_mass, lunar_radius),  288 km, 1 km)
+print("Gravity well depths:")
+print("Sun     {well_depth(solar_mass, solar_radius):8.0f}")
+print("Earth   {well_depth(earth_mass, earth_radius):8.0f}")
+print("Moon    {well_depth(lunar_mass, lunar_radius):8.0f}")
+print("Mars    {well_depth(mars_mass,  mars_radius):8.0f}")
+print("Jupiter {well_depth(jupiter_mass, jupiter_radius):8.0f}")
+
 ```
+
+<p align="center" style="margin-top: 2em"><a href="https://xkcd.com/681/"><img src="https://imgs.xkcd.com/comics/gravity_wells.png" alt="XKCD 681" style="max-width: 100%"></a><br>Source: <a href="https://xkcd.com/681/">https://xkcd.com/681/</a></p>

book/src/example-xkcd_687.md

@@ -18,3 +18,5 @@ let r: Scalar =
 
 print("{r} ≈ π ?")
 ```
+
+<p align="center" style="margin-top: 2em"><a href="https://xkcd.com/687/"><img src="https://imgs.xkcd.com/comics/dimensional_analysis.png" alt="XKCD 687" style="max-width: 100%"></a><br>Source: <a href="https://xkcd.com/687/">https://xkcd.com/687/</a></p>

examples/xkcd_681.nbt

@@ -7,6 +7,13 @@ use extra::astronomy
 fn well_depth(mass: Mass, radius: Length) -> Length =
     G × mass / (g0 × radius) -> km
 
+print("Gravity well depths:")
+print("Sun     {well_depth(solar_mass, solar_radius):8.0f}")
+print("Earth   {well_depth(earth_mass, earth_radius):8.0f}")
+print("Moon    {well_depth(lunar_mass, lunar_radius):8.0f}")
+print("Mars    {well_depth(mars_mass,  mars_radius):8.0f}")
+print("Jupiter {well_depth(jupiter_mass, jupiter_radius):8.0f}")
+
 assert_eq(well_depth(earth_mass, earth_radius), 6379 km, 1 km)
 assert_eq(well_depth(mars_mass,  mars_radius),  1286 km, 3 km)
 assert_eq(well_depth(lunar_mass, lunar_radius),  288 km, 1 km)