Starting point for PR #190

Author: sunjay

Cargo.toml

@@ -51,6 +51,11 @@ cfg-if = "0.1"
 
 parking_lot = "0.10"
 
+# This dependency should be uncommented when rebuilding the images in the API
+# documentation. In all other cases this dependency cannot be used since having
+# a path-only dependency would make it impossible to publish this crate.
+#turtle_docs_helpers = { path = "turtle_docs_helpers" }
+
 [dependencies.futures-util]
 version = "0.3"
 default-features = false

src/async_drawing.rs

@@ -188,3 +188,10 @@ impl AsyncDrawing {
         self.client.debug_drawing().await
     }
 }
+
+#[cfg(docs_images)]
+impl turtle_docs_helpers::SaveDocsSvg for AsyncDrawing {
+    fn save_docs_svg(&self, path: std::path::PathBuf) {
+        self.client.save_docs_svg(path);
+    }
+}

src/async_turtle.rs

@@ -324,3 +324,10 @@ impl AsyncTurtle {
         self.client.debug_turtle(self.id, self.angle_unit).await
     }
 }
+
+#[cfg(docs_images)]
+impl turtle_docs_helpers::SaveDocsSvg for AsyncTurtle {
+    fn save_docs_svg(&self, path: std::path::PathBuf) {
+        self.client.save_docs_svg(path);
+    }
+}

src/drawing.rs

@@ -629,6 +629,13 @@ impl Drawing {
     }
 }
 
+#[cfg(docs_images)]
+impl turtle_docs_helpers::SaveDocsSvg for Drawing {
+    fn save_docs_svg(&self, path: std::path::PathBuf) {
+        self.drawing.save_docs_svg(path);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/ipc_protocol/protocol.rs

@@ -408,3 +408,12 @@ impl ProtocolClient {
         }
     }
 }
+
+#[cfg(docs_images)]
+impl turtle_docs_helpers::SaveDocsSvg for ProtocolClient {
+    fn save_docs_svg(&self, path: std::path::PathBuf) {
+        use crate::sync_runtime::block_on;
+        block_on(self.export_svg(path))
+            .expect("unable to save docs image");
+    }
+}

src/turtle.rs

@@ -535,7 +535,7 @@ impl Turtle {
     ///
     /// # Example
     ///
-    /// ```rust,no_run
+    /// ```rust
     /// use turtle::Turtle;
     ///
     /// fn main() {
@@ -557,6 +557,7 @@ impl Turtle {
     ///     turtle.set_pen_color("#4CAF50"); // green
     ///     turtle.set_pen_size(100.0);
     ///     turtle.forward(200.0);
+    ///     # #[cfg(docs_images)] turtle_docs_helpers::save_docs_image(&turtle, "pen_thickness");
     /// }
     /// ```
     ///
@@ -891,6 +892,13 @@ impl Turtle {
     }
 }
 
+#[cfg(docs_images)]
+impl turtle_docs_helpers::SaveDocsSvg for Turtle {
+    fn save_docs_svg(&self, path: std::path::PathBuf) {
+        self.turtle.save_docs_svg(path);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

turtle_docs_helpers/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "turtle_docs_helpers"
+version = "0.1.0"
+authors = ["Sunjay Varma <[email protected]>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

turtle_docs_helpers/src/lib.rs

@@ -0,0 +1,17 @@
+use std::path::{Path, PathBuf};
+
+/// Saves the image being drawn as an SVG and panics if an error occurs
+///
+/// This is different from the `save_svg` method on `Drawing` and `AsyncDrawing`
+/// because this is only meant to be used for automation and may need to access
+/// internal APIs.
+pub trait SaveDocsSvg {
+    fn save_docs_svg(&self, path: PathBuf);
+}
+
+/// Saves the currently drawn image to `docs/assets/images/docs/{output_name}`
+pub fn save_docs_image<T: SaveDocsSvg>(drawing: &T, output_name: &str) {
+    let svg_path = Path::new("docs/assets/images/docs").join(output_name).with_extension("svg");
+    drawing.save_docs_svg(svg_path);
+    todo!()
+}