Align API for saving/showing plots more closely with plotly.py (#89)

* reconfigure API for saving/showing plots

* update changelog

* update book introduction with new api

Author: mfreeborn

.gitignore

@@ -4,4 +4,5 @@ Cargo.lock
 gh-pages/
 Untitled*
 .ipynb_checkpoints/
-.DS_Store
+.DS_Store
+.vscode

CHANGELOG.md

@@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.8.0] - 2022-xx-xx
+Version 0.8.0 represents a significant release which refactors a lot of the codebase and tries to provide a cleaner API: there are several breaking changes listed below.
 ### Added
 - impl `Clone`, `Serialize` and `PartialEq` for `Plot`
 - impl `Clone` +/- `Copy` for color types
@@ -18,6 +19,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Improve implementation of `private::NumOrString` to support more primitive types ([Issue 
 #47](https://github.com/igiagkiozis/plotly/issues/47))
 - Remove `private::TruthyEnum` in favour of a more robust way of serializing to `String` or `bool`
+- Refactor `Color` module
+- Refactored HTML templates with cleaner Javascript code
+- `Plot::save()` is renamed to `Plot::write_image()`
+- `Plot::show_{png | jpeg}` is now made generic via the new `Plot::show_image()` across static image formats with the `ImageFormat` enum
+- `Plot::write_html()` now takes a filepath and saves the plot to that location
+- `Plot::to_html()` now has similar behaviour to `Plot::to_inline_html()` and just returns a `String`
 ### Fixed
 - Typos in `CONTRIBUTING.md`
 - Serialization of `plotly_kaleido::PlotData` ([Issue #50](https://github.com/igiagkiozis/plotly/issues/50))
@@ -26,8 +33,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `serde` to `1.0.132`.
 - `serde_json` to `1.0.73`.
 - `askama` to `0.11.0`.
-- `rand` to `0.8.4`.
-- `rand_distr` to `0.4.2`.
+- `rand` to `0.8`.
+- `rand_distr` to `0.4`.
 - `plotly.js` to `2.12.1`
 
 ## [0.7.0] - 2022-01-01

docs/book/src/getting_started.md

@@ -18,38 +18,28 @@
 
 # Getting Started
 
-To start using [Plotly.rs](https://github.com/igiagkiozis/plotly) in your project add the following to your `Cargo.toml`:
+To start using [plotly.rs](https://github.com/igiagkiozis/plotly) in your project add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
 plotly = "0.7.0"
 ```
 
-To add the ability to save plots in the following formats: png, jpeg, webp, svg, pdf and eps, you can use the `kaleido` feature. This feature depends on [plotly/Kaleido](https://github.com/plotly/Kaleido); a cross-platform library for generating static images. All the necessary binaries have been included with `plotly_kaleido` for `linux`, `windows` and `macos`. Previous versions of [Plotly.rs](https://github.com/igiagkiozis/plotly) used the `orca` feature; however this has been deprecated as it provided the same functionality but required additional installation steps. To enable the `kaleido` feature add the following to your `Cargo.toml` instead: 
+[Plotly.rs](https://github.com/igiagkiozis/plotly) is ultimately a thin wrapper around the `plotly.js` library. The main job of this library is to provide `structs` and `enums` which get serialized to `json` and passed to the `plotly.js` library to actually do the heavy lifting. As such, if you are familiar with `plotly.js` or its derivatives (e.g. the equivalent Python library), then you should find [`plotly.rs`](https://github.com/igiagkiozis/plotly) intuitive to use.
 
-```toml
-[dependencies]
-plotly = { version = "0.7.0", features = ["kaleido"] }
-```
+A `Plot` struct contains one or more `Trace` objects which describe the structure of data to be displayed. Optional `Layout` and `Configuration` structs can be used to specify the layout and config of the plot, respectively.
 
-Plotly Kaleido is an open source project 
+The builder pattern is used extensively throughout the library, which means you only need to specify the attributes and details you desire. Any attributes that are not set will fall back to the default value used by `plotly.js`.
 
-
-[Plotly.rs](https://github.com/igiagkiozis/plotly) has three main components: 
-
-- Traces; these are containers for the data for display,
-- Layout, fine tunes the display of traces on the canvas and more generally controls the way that the plot is displayed, and,
-- Plot; is the component that brings traces and the layout together to display the plot in either html format or rasterise the resulting view.
-
-All available traces (e.g. `Scatter`, `Bar`, `Histogram` etc), the `Layout` and `Plot` have been hoisted in the `plotly` namespace so that they can be imported simply using the following: 
+All available traces (e.g. `Scatter`, `Bar`, `Histogram`, etc), the `Layout`, `Configuration` and  `Plot` have been hoisted in the `plotly` namespace so that they can be imported simply using the following: 
 
 ```rust
 use plotly::{Plot, Layout, Scatter};
 ```
 
 The aforementioned components can be combined to produce as simple plot as follows: 
+
 ```rust
-extern crate plotly;
 use plotly::common::Mode;
 use plotly::{Plot, Scatter};
 
@@ -75,26 +65,37 @@ fn main() -> std::io::Result<()> {
 }
 ```
 
-which results in the following figure: 
+which results in the following figure (displayed here as a static png file): 
 
 ![line_and_scatter_plot](img/line_and_scatter_plot.png)
 
-The above code will generate an html page of the `Plot` and display it in the default browser. The `html` for the plot is stored in the platform specific temporary directory. To save the `html` result the following can be used: 
+The above code will generate an interactive `html` page of the `Plot` and display it in the default browser. The `html` for the plot is stored in the platform specific temporary directory. To save the `html` result, you can do so quite simply: 
 
 ```rust
-plot.to_html("/home/user/line_and_scatter_plot.html");
+plot.write_html("/home/user/line_and_scatter_plot.html");
 ```
 
-It is often the case that plots are produced to be included in a document and a different format for the plot is desirable (e.g. png, jpeg etc). Given that the `html` version of the plot is composed of vector graphics, the display when converted to a non-vector format (e.g. png) is not guaranteed to be identical to the one displayed in `html`. This means that some fine tuning may be required to get to the desired output. To support that iterative workflow the `Plot` has `show_*` methods which display the rasterised output to the target format, for example this: 
+It is often the case that plots are produced to be included in a document and a different format for the plot is desirable (e.g. png, jpeg, etc). Given that the `html` version of the plot is composed of vector graphics, the display when converted to a non-vector format (e.g. png) is not guaranteed to be identical to the one displayed in `html`. This means that some fine tuning may be required to get to the desired output. To support that iterative workflow, `Plot` has a `show_image()` method which will display the rasterised output to the target format, for example: 
 
 ```rust
-plot.show_png(1280, 900);
+plot.show_image(ImageFormat::PNG, 1280, 900);
 ```
 
-will display in the browser the rasterised plot; 1280 pixels wide and 900 pixels tall, in png format. Once a satisfactory result is achieved, and assuming the `kaleido` feature is enabled, the plot can be saved using the following: 
+will display in the browser the rasterised plot; 1280 pixels wide and 900 pixels tall, in png format.
+
+Once a satisfactory result is achieved, and assuming the [`kaleido`](getting_started#saving-plots) feature is enabled, the plot can be saved using the following: 
 
 ```rust
-plot.save("/home/user/plot_name.ext", ImageFormat::PNG, 1280, 900, 1.0);
+plot.write_image("/home/user/plot_name.ext", ImageFormat::PNG, 1280, 900, 1.0);
 ```
 
-The extension in the file-name path is optional as the appropriate extension (`ImageFormat::PNG`) will be included. Note that in all functions that save files to disk both relative and absolute paths are supported.
+The extension in the file-name path is optional as the appropriate extension (`ImageFormat::PNG`) will be included. Note that in all functions that save files to disk, both relative and absolute paths are supported.
+
+## Saving Plots
+
+To add the ability to save plots in the following formats: png, jpeg, webp, svg, pdf and eps, you can use the `kaleido` feature. This feature depends on [plotly/Kaleido](https://github.com/plotly/Kaleido): a cross-platform open source library for generating static images. All the necessary binaries have been included with `plotly_kaleido` for `Linux`, `Windows` and `MacOS`. Previous versions of [plotly.rs](https://github.com/igiagkiozis/plotly) used the `orca` feature, however, this has been deprecated as it provided the same functionality but required additional installation steps. To enable the `kaleido` feature add the following to your `Cargo.toml`: 
+
+```toml
+[dependencies]
+plotly = { version = "0.7.0", features = ["kaleido"] }
+```

docs/book/src/plotly_rs.md

@@ -18,16 +18,19 @@
 
 # Plotly.rs
 
-Plotly.rs is a plotting library powered by [Plotly.js](https://plot.ly/javascript/). The aim is to bring over to Rust all the functionality that `Python` users have come to rely on; with the added benefit of type safety and speed.
+Plotly.rs is a plotting library powered by [Plotly.js](https://plot.ly/javascript/). The aim is to bring over to Rust all the functionality that `Python` users have come to rely on with the added benefit of type safety and speed.
 
 Plotly.rs is free and open source. You can find the source on [GitHub](https://github.com/igiagkiozis/plotly). Issues and feature requests can be posted on the [issue tracker](https://github.com/igiagkiozis/plotly/issues).
 
 ## API Docs
 
-This book is intended to be a *recipe* index and is complemented by the [API documentation](https://docs.rs/plotly).
+This book is intended to be a recipe index, which closely follows the [plotly.js examples](https://plotly.com/javascript/), and is complemented by the [API documentation](https://docs.rs/plotly).
+
+## Contributing
+Contributions are always welcomed, no matter how large or small. Refer to the [contributing guidelines](https://github.com/igiagkiozis/plotly/blob/master/CONTRIBUTING.md) for further pointers, and, if in doubt, [open an issue](https://github.com/igiagkiozis/plotly/issues).
 
 ## License
 
 Plotly.rs is distributed under the terms of the MIT license.
 
-See [LICENSE-MIT](LICENSE-MIT), and [COPYRIGHT](COPYRIGHT) for details.
+See [LICENSE-MIT](https://github.com/igiagkiozis/plotly/blob/master/LICENSE-MIT), and [COPYRIGHT](https://github.com/igiagkiozis/plotly/blob/master/COPYRIGHT) for details.

plotly/Cargo.toml

@@ -32,8 +32,8 @@ once_cell = "1"
 serde = { version = "1.0.132", features = ["derive"] }
 serde_json = "1.0.73"
 serde_repr = "0.1"
-rand = "0.8.4"
-rand_distr = "0.4.2"
+rand = "0.8"
+rand_distr = "0.4"
 wasm-bindgen = { version = "0.2", optional = true }
 wasm-bindgen-futures = { version = "0.4", optional = true }