add pie unittests and fix docs

Signed-off-by: Andrei Gherghescu <[email protected]>

Author: andrei-ng

docs/book/src/recipes/basic_charts/pie_charts.md

@@ -20,6 +20,12 @@ The `to_inline_html` method is used to produce the html plot displayed in this p
 
 {{#include ../../../../../examples/basic_charts/out/basic_pie_chart.html}}
 
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:basic_pie_chart_labels}}
+```
+
+{{#include ../../../../../examples/basic_charts/out/basic_pie_chart_labels.html}}
+
 ## Grouped Pie Chart
 ```rust,no_run
 {{#include ../../../../../examples/basic_charts/src/main.rs:grouped_donout_pie_charts}}

examples/basic_charts/src/main.rs

@@ -825,7 +825,7 @@ fn table_chart(show: bool) -> Plot {
 // Pie Charts
 // ANCHOR: basic_pie_chart
 fn basic_pie_chart(show: bool) -> Plot {
-    let values = vec![2, 3, 5];
+    let values = vec![2, 3, 4];
     let labels = vec!["giraffes", "orangutans", "monkeys"];
     let t = Pie::new(values).labels(labels);
     let mut plot = Plot::new();
@@ -838,6 +838,23 @@ fn basic_pie_chart(show: bool) -> Plot {
 }
 // ANCHOR_END: basic_pie_chart
 
+// ANCHOR: basic_pie_chart_labels
+fn basic_pie_chart_labels(show: bool) -> Plot {
+    let labels = vec!["giraffes", "giraffes", "orangutans", "monkeys"]
+        .iter()
+        .map(|s| s.to_string())
+        .collect();
+    let t = Pie::<u32>::from_labels(labels);
+    let mut plot = Plot::new();
+    plot.add_trace(t);
+
+    if show {
+        plot.show();
+    }
+    plot
+}
+// ANCHOR_END: basic_pie_chart_labels
+
 // ANCHOR: pie_chart_text_control
 fn pie_chart_text_control(show: bool) -> Plot {
     let values = vec![2, 3, 4, 4];
@@ -992,7 +1009,8 @@ fn main() {
     write_example_to_html(basic_sankey_diagram(false), "basic_sankey_diagram");
 
     // Pie Charts
-    write_example_to_html(basic_pie_chart(false), "basic_pie_chart");
+    write_example_to_html(basic_pie_chart(true), "basic_pie_chart");
+    write_example_to_html(basic_pie_chart_labels(true), "basic_pie_chart_labels");
     write_example_to_html(pie_chart_text_control(false), "pie_chart_text_control");
     write_example_to_html(
         grouped_donout_pie_charts(false),

plotly/src/layout/mod.rs

@@ -1071,8 +1071,8 @@ pub struct Annotation {
     visible: Option<bool>,
     /// Sets the text associated with this annotation. Plotly uses a subset of
     /// HTML tags to do things like newline (<br>), bold (<b></b>), italics
-    /// (<i></i>), hyperlinks (<a href='...'></a>). Tags <em></em>, <sup></sup>, <sub></sub>
-    /// <span></span> are also supported.
+    /// (<i></i>), hyperlinks (<a href='...'></a>). Tags <em></em>, <sup></sup>,
+    /// <sub></sub> <span></span> are also supported.
     text: Option<String>,
     /// Sets the angle at which the `text` is drawn with respect to the
     /// horizontal.

plotly/src/traces/pie.rs

@@ -35,6 +35,28 @@ pub enum PieDirection {
 ///
 /// assert_eq!(serde_json::to_value(trace).unwrap(), expected);
 /// ```
+/// # Using only labels
+///
+/// Build a new Pie Chart by only assigning the labels field. The Pie chart
+/// will be generated by counting the number of unique labels, see [Pie::labels]
+/// field description. Note that to create a Pie chart by using this
+/// function, the type parameter `P` needs to be specialized, this can be
+/// done by doing
+///
+/// ```
+/// use plotly::Pie;
+///
+/// let labels = vec!["giraffes", "giraffes", "orangutans", "monkeys"].iter().map(|s| s.to_string()).collect();
+///
+/// let trace = Pie::<u32>::from_labels(labels);
+///
+/// let expected = serde_json::json!({
+///     "type": "pie",
+///     "labels": ["giraffes", "giraffes", "orangutans", "monkeys"],
+/// });
+///
+/// assert_eq!(serde_json::to_value(trace).unwrap(), expected);
+/// ```
 #[serde_with::skip_serializing_none]
 #[derive(Serialize, Clone, Debug, FieldSetter)]
 #[field_setter(box_self, kind = "trace")]
@@ -86,9 +108,9 @@ where
     /// Additionally, every attributes that can be specified per-point (the
     /// ones that are arrayOk: true) are available.  Finally, the template
     /// string has access to variables label, color, value, percent and text.
-    /// Anything contained in tag \<extra\> is displayed in the secondary box, for
-    /// example “<extra>{fullData.name}</extra>”. To hide the secondary box
-    /// completely, use an empty tag <extra></extra>.
+    /// Anything contained in tag \<extra\> is displayed in the secondary box,
+    /// for example “<extra>{fullData.name}</extra>”. To hide the secondary
+    /// box completely, use an empty tag <extra></extra>.
     #[serde(rename = "hovertemplate")]
     hover_template: Option<Dim<String>>,
     /// Sets hover text elements associated with each sector. If a single
@@ -144,9 +166,9 @@ where
     /// axis and colorbar title.text, annotation text rangeselector,
     /// updatemenues and sliders label text all support meta. To access the
     /// trace meta values in an attribute in the same trace, simply use
-    /// %{meta\[i\]} where i is the index or key of the meta item in question. To
-    /// access trace meta in layout attributes, use %{data[n[.meta\[i\]} where i
-    /// is the index or key of the meta and n is the trace index.
+    /// %{meta\[i\]} where i is the index or key of the meta item in question.
+    /// To access trace meta in layout attributes, use %{data[n[.meta\[i\]}
+    /// where i is the index or key of the meta and n is the trace index.
     meta: Option<NumOrString>,
     /// Sets the trace name. The trace name appears as the legend item and on
     /// hover.
@@ -186,10 +208,10 @@ where
     /// Template string used for rendering the information text that appear on
     /// points. Note that this will override textinfo. Variables are
     /// inserted using %{variable}, for example “y: %{y}”. Numbers are formatted
-    /// using d3-format’s syntax %{variable:d3-format},  for example “Price: %{y:$.2f}”.
-    /// <https://github.com/d3/d3-format/tree/v1.4.5#d3-format> for details on the formatting syntax.
-    /// Dates are formatted using d3-time-format’s syntax %{variable|d3-time-format}, for example
-    /// “Day: %{2019-01-01|%A}”. <https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format> for details on the date formatting syntax.
+    /// using d3-format’s syntax %{variable:d3-format},  for example “Price:
+    /// %{y:$.2f}”. <https://github.com/d3/d3-format/tree/v1.4.5#d3-format> for details on the formatting syntax.
+    /// Dates are formatted using d3-time-format’s syntax
+    /// %{variable|d3-time-format}, for example “Day: %{2019-01-01|%A}”. <https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format> for details on the date formatting syntax.
     /// Every attributes that can be specified per-point (the ones that are
     /// arrayOk: true) are available. Finally, the template string has
     /// access to variables label, color, value, percent and text.
@@ -282,9 +304,36 @@ impl<P> Pie<P>
 where
     P: Serialize + Clone + 'static,
 {
-    pub fn new(x: Vec<P>) -> Box<Self> {
+    /// Build a new Pie Chart by only assigning the values field
+    pub fn new(values: Vec<P>) -> Box<Self> {
+        Box::new(Self {
+            values: Some(values),
+            ..Default::default()
+        })
+    }
+
+    /// Same as [Pie::new()]
+    pub fn from_values(values: Vec<P>) -> Box<Self> {
         Box::new(Self {
-            values: Some(x),
+            values: Some(values),
+            ..Default::default()
+        })
+    }
+
+    /// Build a new Pie Chart by only assigning the labels field. The Pie chart
+    /// will be generated by counting the number of unique labels, see
+    /// [Pie::labels] field description. Note that to create a Pie chart by
+    /// using this function, the type parameter `P` needs to be specialized,
+    /// this can be done by doing
+    /// ```
+    /// use plotly::Pie;
+    ///
+    /// let labels = vec!["giraffes", "giraffes", "orangutans", "monkeys"].iter().map(|s| s.to_string()).collect();
+    /// let trace = Pie::<u32>::from_labels(labels);
+    /// ```
+    pub fn from_labels(labels: Vec<String>) -> Box<Self> {
+        Box::new(Self {
+            labels: Some(labels),
             ..Default::default()
         })
     }
@@ -306,8 +355,8 @@ mod tests {
     use super::*;
 
     #[test]
-    fn test_serialize_scatter_mapbox() {
-        let scatter_mapbox = Pie::new(vec![45, 55])
+    fn serialize_pie() {
+        let pie_trace = Pie::new(vec![45, 55])
             .name("pie")
             .automargin(true)
             .direction(PieDirection::Clockwise)
@@ -374,6 +423,36 @@ mod tests {
             "uirevision": 6,
         });
 
-        assert_eq!(to_value(scatter_mapbox).unwrap(), expected);
+        assert_eq!(to_value(pie_trace).unwrap(), expected);
+    }
+
+    #[test]
+    fn new_from_values() {
+        let values = vec![2.2, 3.3, 4.4];
+        let trace = Pie::from_values(values);
+
+        let expected = serde_json::json!({
+            "type": "pie",
+            "values": [2.2, 3.3, 4.4],
+        });
+
+        assert_eq!(to_value(trace).unwrap(), expected);
+    }
+
+    #[test]
+    fn new_from_labels() {
+        let labels = vec!["giraffes", "giraffes", "orangutans", "monkeys"]
+            .iter()
+            .map(|s| s.to_string())
+            .collect();
+
+        let trace = Pie::<u32>::from_labels(labels);
+
+        let expected = serde_json::json!({
+            "type": "pie",
+            "labels": ["giraffes", "giraffes", "orangutans", "monkeys"],
+        });
+
+        assert_eq!(to_value(trace).unwrap(), expected);
     }
 }