Merge pull request #65 from cpmech/rename-save-and-show-functions

Rename save and show functions

src/lib.rs

@@ -18,15 +18,18 @@
 //! should be useful for double checking or even directly adding Python/Matplotlib commands,
 //! in case the functionality is not implemented here yet.
 //!
-//! When calling [Plot::save] or [Plot::save_and_show], if an error occurs, we generate a log
+//! When calling [Plot::save()] or [Plot::show()], if an error occurs, we generate a log
 //! file in the same output directory with the same filename as the figure (and python script),
 //! but with the `.log` extension.
 //!
 //! The typical use of this library is by allocating structures such as [Canvas], [Curve], [Contour],
 //! [Histogram], [Surface], [Text] (and more) and then passing them to [Plot] for the generation
-//! of the files mentioned above. The [Plot::save_and_show] function may also be used to immediately
+//! of the files mentioned above. The [Plot::show()] function may also be used to immediately
 //! see the plot or drawing on the screen.
 //!
+//! Alternatively, [if evcxr is installed](https://github.com/evcxr/evcxr), the function
+//! [Plot::show_in_jupyter()] can be used to show the resulting figure in a Jupyter notebook.
+//!
 //! Each structure (e.g. [Curve], [Legend], or [Text]) defines many configuration options
 //! that can be set by calling their own `set_...` function. Typically, these structures provide
 //! `draw_...` functions to plot/draw features. Afterwards, we call [Plot::add] to add these structures

src/plot.rs

@@ -203,53 +203,60 @@ impl Plot {
         self
     }
 
-    /// Calls python3 and saves the python script and figure
+    /// Calls Python and saves the python script and figure
     ///
     /// # Input
     ///
     /// * `figure_path` -- may be a String, &str, or Path
     ///
-    /// # Note
+    /// # Notes
     ///
-    /// Call `set_show_errors` to configure how the errors (if any) are printed.
+    /// 1. You may want to call [Plot::set_show_errors()] to enable the
+    ///    display of Python errors (if any)
     pub fn save<S>(&self, figure_path: &S) -> Result<(), StrError>
     where
         S: AsRef<OsStr> + ?Sized,
     {
         self.run(figure_path, false)
     }
 
-    /// Calls python3, saves the python script and figure, and show the plot window
+    /// Calls Python, saves the python script and figure, and shows the plot window
     ///
     /// # Input
     ///
     /// * `figure_path` -- may be a String, &str, or Path
     ///
-    /// # Note
+    /// # Notes
     ///
-    /// Call `set_show_errors` to configure how the errors (if any) are printed.
-    pub fn save_and_show<S>(&self, figure_path: &S) -> Result<(), StrError>
+    /// 1. You may want to call [Plot::set_show_errors()] to enable the
+    ///    display of Python errors (if any)
+    /// 2. This function will also save a figure as [Plot::save()] does
+    pub fn show<S>(&self, figure_path: &S) -> Result<(), StrError>
     where
         S: AsRef<OsStr> + ?Sized,
     {
         self.run(figure_path, true)
     }
 
-    /// Show the plot in `evcxr` kernel Jupyter Notebook
+    /// Calls Python, saves the python script and figure, and shows the result in a Jupyter notebook
+    ///
+    /// **Important:** This function requires [evcxr_jupyter](https://github.com/evcxr/evcxr).
     ///
     /// # Input
     ///
     /// * `figure_path` -- may be a String, &str or Path
     ///
-    /// # Note
+    /// # Notes
     ///
-    /// 1. This method only works in a Jupyter Notebook
-    /// 2. The input must be the same saved by `plot.save(...)`. Thus, make sure
-    ///    that the plot has been saved before calling `plot.show_in_evcxr()`.
-    pub fn show_in_evcxr<S>(&self, figure_path: &S) -> Result<(), StrError>
+    /// 1. You may want to call [Plot::set_show_errors()] to enable the
+    ///    display of Python errors (if any)
+    /// 2. This function will also save a figure as [Plot::save()] does
+    /// 3. This method only works in a Jupyter Notebook
+    pub fn show_in_jupyter<S>(&self, figure_path: &S) -> Result<(), StrError>
     where
         S: AsRef<OsStr> + ?Sized,
     {
+        self.run(figure_path, false)?;
         let fig_path = Path::new(figure_path);
         match fs::read_to_string(fig_path) {
             Ok(figure) => println!("EVCXR_BEGIN_CONTENT text/html\n{}\nEVCXR_END_CONTENT", figure),
@@ -305,7 +312,7 @@ impl Plot {
         self.legend()
     }
 
-    /// Sets flag to print python errors (if any) when calling save
+    /// Enables the display of python errors (if any)
     pub fn set_show_errors(&mut self, option: bool) -> &mut Self {
         self.show_errors = option;
         self
@@ -1125,7 +1132,7 @@ mod tests {
         let plot = Plot::new();
         let path = Path::new(OUT_DIR).join("show_works.svg");
         plot.save(&path).unwrap();
-        let result = plot.show_in_evcxr(&path).unwrap();
+        let result = plot.show_in_jupyter(&path).unwrap();
         assert_eq!(result, ());
     }