docs: go-plot v0.2.0 — pie and donut, CSP-safe SVG

README.md

@@ -25,7 +25,7 @@ while no release is tagged:
 
 `https://go-plot.github.io/docs/` redirects to `latest/`. Each push to `main`
 replaces the directory of the version it describes, and nothing else. The
-pages describe **v0.1.0**, published under `0.1/`.
+pages describe **v0.2.0**, published under `0.2/`.
 
 To document a new release, set `params.plot.version` to its tag, require the
 same version in `figures/go.mod`, redraw the figures, and update the pages.
@@ -68,10 +68,10 @@ cd figures && go run .
 git clone --recurse-submodules https://github.com/go-plot/docs.git
 cd docs
 mkdir -p data && sh themes/hextra/scripts/page-history.sh > data/pagehistory.json
-hugo server --baseURL http://localhost:1313/docs/0.1/
+hugo server --baseURL http://localhost:1313/docs/0.2/
 ```
 
-then open <http://localhost:1313/docs/0.1/>. Hugo 0.146 or later; no Python,
+then open <http://localhost:1313/docs/0.2/>. Hugo 0.146 or later; no Python,
 no Node. Go 1.27.2 or later only to redraw the figures.
 
 ## Publication

content/en/_index.md

@@ -20,13 +20,16 @@ set by a real TeX math typesetter, [go-tex/math](https://github.com/go-tex/math)
 <img class="figure" src="images/figures/quickstart.svg" alt="A sine curve drawn as a line and as markers, with a TeX label and a legend">
 
 These pages describe [go-plot/plot](https://github.com/go-plot/plot)
-**v0.1.0**. Every figure in them was drawn by that version, from the code shown
-beside it.
+**v0.2.0**. Every figure in them was drawn by that version, from the code shown
+beside it. New in v0.2.0:
+
+- [pie and donut charts]({{< relref "plot-types#pie-and-donut" >}}).
+- An SVG that can be inlined under a strict Content-Security-Policy.
 
 ## Install
 
 ```sh
-go get github.com/go-plot/plot@v0.1.0
+go get github.com/go-plot/plot@v0.2.0
 ```
 
 The module needs Go 1.27.2 or later. It is pure Go (`CGO_ENABLED=0`) and builds

content/en/differences.md

@@ -68,6 +68,34 @@ a pad. Usually the same place; not always.
 The SVG carries the same geometry but not matplotlib's document structure, ids
 or metadata.
 
+Since v0.2.0 the SVG can be inlined in an HTML page served under a strict
+Content-Security-Policy:
+
+- Paint is in presentation attributes (`fill="…"`), not `style="…"`, which a
+  `style-src` without `'unsafe-inline'` would drop.
+- There is no script and no event attribute.
+- No reference leaves the document.
+- Text is glyph outlines, so no label can become markup.
+- A clip's id is derived from its rectangle, so two figures inlined in one page
+  cannot clip each other.
+
+The one `data:` URI is an `Imshow` image.
+
+### Pie
+
+`Pie` is `ax.pie` with matplotlib's defaults. It differs in six places:
+
+- The refusals (negative, NaN, infinite, all zero) are returned as
+  `ErrPieNegative`, `ErrPieNonFinite` and `ErrPieZero`, not raised.
+- A sum of sizes that overflows is taken after scaling, where matplotlib draws
+  every wedge empty.
+- `AutoPct` takes Go format verbs (`"%1.1f%%"` works in both; Python's `%d`
+  is Go's `%.0f`).
+- `labeldistance=None` is `LabelDistance(math.NaN())`.
+- There is no `shadow`, no `hatch` and no `frame=True`.
+- `Donut`, `PlainText` (labels never reach TeX) and `SpreadLabels` (labels of
+  thin wedges moved apart, with leader lines) are go-plot's own.
+
 ### No module-level pyplot
 
 `plt.plot`, `plt.xlabel` and the other functions acting on a hidden current
@@ -82,7 +110,7 @@ Axes are not provided, by design: see [the API]({{< relref "api" >}}).
 - `constrained_layout`;
 - `subplots` sharing;
 - hatching;
-- boxplot, violin, pie, quiver, stem, step, `pcolormesh`, 3-D;
+- boxplot, violin, quiver, stem, step, `pcolormesh`, 3-D;
 - colorbar `extend` and discrete norms;
 - image interpolation other than nearest;
 - `Text` bounding boxes;

content/en/getting-started.md

@@ -8,7 +8,7 @@ tags: [start]
 ## Install
 
 ```sh
-go get github.com/go-plot/plot@v0.1.0
+go get github.com/go-plot/plot@v0.2.0
 ```
 
 Go 1.27.2 or later. Nothing else: no Python, no C library, no font to install.

content/en/plot-types.md

@@ -5,7 +5,7 @@ description: "Every plot type of v0, each with the code that drew it."
 tags: [api, gallery]
 ---
 
-Each figure on this page was drawn by go-plot v0.1.0 from the code below it.
+Each figure on this page was drawn by go-plot v0.2.0 from the code below it.
 The code is not a copy: the page reads it from
 [`figures/`](https://github.com/go-plot/docs/tree/main/figures) in this
 site's repository, where `go run .` draws every image, and the CI draws them
@@ -23,6 +23,7 @@ again and fails if any differs from the one shown. `linspace` is a helper in
 | reference lines | `Axhline`, `Axvline` | `ax.axhline`, `ax.axvline` |
 | images | `Imshow` (2-D data or RGB(A)) | `ax.imshow` |
 | contours | `Contour`, `Contourf` | `ax.contour`, `ax.contourf` |
+| pies, rings | `Pie`, `Donut` | `ax.pie`, `ax.pie(wedgeprops=dict(width=w))` |
 | text | `Text`, `Annotate` | `ax.text`, `ax.annotate` |
 | scales, axes | `SetXScale("log")`, `TwinX`, `SetXTicks`, `SetAspect` | `ax.set_xscale`, `ax.twinx`, `ax.set_xticks`, `ax.set_aspect` |
 | colour scale | `Figure.Colorbar` | `fig.colorbar` |
@@ -78,6 +79,33 @@ the column and row coordinates.
 
 {{< plotfig "contour" "Filled contours of a two-dimensional function in RdBu_r with black contour lines and a colorbar" >}}
 
+## Pie and donut
+
+`Pie` is matplotlib's `ax.pie`.
+
+- Wedge i covers `x[i]/sum(x)` of a turn, from 3 o'clock counter-clockwise, in
+  the colours of the cycle.
+- Labels sit at 1.1 radii, and `AutoPct` percentages at 0.6.
+- The Axes gets an equal aspect, no frame and no ticks.
+- The judge against matplotlib compares every wedge path vertex by vertex,
+  every label's position and alignment, the Axes box, and ≥ 99% of the pixels.
+
+Sizes that are negative, NaN, infinite or all zero return an error
+(`ErrPieNegative`, `ErrPieNonFinite`, `ErrPieZero`) and draw nothing, as
+matplotlib raises.
+
+`Donut(x, width)` is a ring, with the percentages in its middle. Two go-plot
+options matter for data-driven charts:
+
+- `PlainText()` sets the labels as they are, with no TeX: "$5" is a dollar.
+- `SpreadLabels()` moves the labels of thin wedges apart, with leader lines.
+
+`StartAngle(90), CounterClock(false)` starts at 12 o'clock and runs clockwise,
+as go-widgets/toolkit's interactive `PieChart` does.
+`Colors(colors.Tableau10...)` gives the toolkit's palette.
+
+{{< plotfig "pie" "A pie of four expense categories with percentages, and a donut with white edges and its percentages on the ring" >}}
+
 ## Log scales
 
 `SetXScale("log")` and `SetYScale("log")` use matplotlib's `LogLocator` and

figures/go.mod

@@ -3,15 +3,15 @@ module github.com/go-plot/docs/figures
 go 1.27.2
 
 require (
-	github.com/go-ndarray/ndarray v0.11.0
-	github.com/go-plot/plot v0.1.0
+	github.com/go-ndarray/ndarray v0.18.0
+	github.com/go-plot/plot v0.2.0
 )
 
 require (
 	github.com/andybalholm/brotli v1.2.6 // indirect
-	github.com/go-gfx/gfx v0.35.0 // indirect
-	github.com/go-opentype/fonts v0.12.0 // indirect
-	github.com/go-opentype/opentype v0.15.0 // indirect
+	github.com/go-gfx/gfx v0.36.0 // indirect
+	github.com/go-opentype/fonts v0.14.0 // indirect
+	github.com/go-opentype/opentype v0.16.0 // indirect
 	github.com/go-tex/math v0.50.0 // indirect
-	github.com/go-widgets/painter v0.15.0 // indirect
+	github.com/go-widgets/painter v0.16.0 // indirect
 )

figures/go.sum

@@ -1,18 +1,18 @@
 github.com/andybalholm/brotli v1.2.6 h1:ftYnfj6usCp+UGV5kSJ3+chpMQgU+gJf/AxsUQ52REI=
 github.com/andybalholm/brotli v1.2.6/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
-github.com/go-gfx/gfx v0.35.0 h1:AaXMxDMxNB1hROxzx+3EoO06KxsrQUvnw/10olmSgVo=
-github.com/go-gfx/gfx v0.35.0/go.mod h1:qIZS9u2+VnBk5CX7o4f/fQ5uD8c+mPFTtAPE85s8V90=
-github.com/go-ndarray/ndarray v0.11.0 h1:HMW7rAI25wSNNgVxOFTYCz48vW/wIBRT8IN17DNZHQ8=
-github.com/go-ndarray/ndarray v0.11.0/go.mod h1:ZcgNCBVLXt1FxeZjQWI5Z+k0SSWAT0/wR8slfat/gRA=
-github.com/go-opentype/fonts v0.12.0 h1:gjYYkbDZBK3JHpraakgGNnXdkGq8oADerhDYjC22ILQ=
-github.com/go-opentype/fonts v0.12.0/go.mod h1:Kiep7ojxxaR2ALFeB/akcFHQyl1gG5OLIobp8EzaZSA=
-github.com/go-opentype/opentype v0.15.0 h1:ioE3eCbNZavlk/w073J3uX5FKjqhgOHQw+wZZdJ+gE4=
-github.com/go-opentype/opentype v0.15.0/go.mod h1:ZB31jTJl2mhPESXYMuUW+p36UrOabw/2+6mtyh/vNnI=
-github.com/go-plot/plot v0.1.0 h1:Zjr7TRE/BGjeqh33lHLBMIsmpf4fHzmgnR5WBzjKUBA=
-github.com/go-plot/plot v0.1.0/go.mod h1:XecnrP78pyClISxwrNlSThaYlEqkmOtTs00N1WQRV/o=
+github.com/go-gfx/gfx v0.36.0 h1:jhreh93w4TAYyF5uUPfkD624QaaMYj6T8UcRZXraTIQ=
+github.com/go-gfx/gfx v0.36.0/go.mod h1:vKqizDoG9dRvh3e9gidrf8AiauQWkpTozcAr3xpXbb8=
+github.com/go-ndarray/ndarray v0.18.0 h1:EE4IDUCAZ0e7DYBs4OrftMG+GGp+jsnvojhDdGh6k5A=
+github.com/go-ndarray/ndarray v0.18.0/go.mod h1:TTobL0ZK6yCvPClMmnT98WUYEtaxoo2B+n0Q/Vc/s0E=
+github.com/go-opentype/fonts v0.14.0 h1:WHw7k9gkHT1pu9B2yyvd0FWyQqn/4NKFQoKhvMYt3Mo=
+github.com/go-opentype/fonts v0.14.0/go.mod h1:od2QcmdpKo7QCqo6Jb16y4GULk+h2Hhfq6x3xfvn62Q=
+github.com/go-opentype/opentype v0.16.0 h1:8FnPhPXQ0E3dVqfGlf8wh/v9g0eIFc7tlzUH4yi2Lu4=
+github.com/go-opentype/opentype v0.16.0/go.mod h1:ZB31jTJl2mhPESXYMuUW+p36UrOabw/2+6mtyh/vNnI=
+github.com/go-plot/plot v0.2.0 h1:EOIL3Nvrp2kos6uhoECTMA8tQSSQv50xGVuMqVVoJG4=
+github.com/go-plot/plot v0.2.0/go.mod h1:+uBqMFBVLL8kAeJ7hcPfThYKV1n26Crqi3eSruc1+qg=
 github.com/go-tex/math v0.50.0 h1:YHJ3LYzS45zBoPKGBkZW4+LUQkOeHP30YWLsfXGZCpo=
 github.com/go-tex/math v0.50.0/go.mod h1:cPm5juijQkhFj1MCByLF8tOfZ+UswAGUPBh+Wy6+vbw=
-github.com/go-widgets/painter v0.15.0 h1:0oeaRDTPcIe5/b0wHtYbAUsnReoidkSapr8y+iZJwDk=
-github.com/go-widgets/painter v0.15.0/go.mod h1:FSLNdrtzfDF3md+vtaORyS4nrOKLW6eLaCT5BuO9EWg=
+github.com/go-widgets/painter v0.16.0 h1:j8FFObisySQChY2JiXS7Di2Mo4cqufIc0PDUnoDPMiA=
+github.com/go-widgets/painter v0.16.0/go.mod h1:3wKWjaM8ZgEhir2HX0UDt8GemePKJ7l/yIjQb/vVSWk=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=

figures/pie.go

@@ -0,0 +1,23 @@
+package main
+
+import "github.com/go-plot/plot"
+
+func init() { register("pie", pie) }
+
+func pie() *plot.Figure {
+	spend := []float64{42, 27, 18, 13}
+	names := []string{"Salaries", "Rent", "Travel", "Other"}
+	fig, axs := plot.Subplots(1, 2, plot.FigSize(8, 4))
+	left, right := axs[0][0], axs[0][1]
+	if err := left.Pie(spend, plot.Labels(names...), plot.AutoPct("%1.1f%%"),
+		plot.PlainText(), plot.Explode(0.05, 0, 0, 0)); err != nil {
+		panic(err)
+	}
+	left.SetTitle("Pie")
+	if err := right.Donut(spend, 0.35, plot.Labels(names...), plot.AutoPct("%.0f%%"),
+		plot.PlainText(), plot.EdgeColor("w"), plot.StartAngle(90), plot.CounterClock(false)); err != nil {
+		panic(err)
+	}
+	right.SetTitle("Donut, from 12 o'clock, clockwise")
+	return fig
+}

hugo.yaml

@@ -6,7 +6,7 @@
 # version of go-plot/plot the pages describe (0.1, 0.2, ...), or "main" while no
 # release is tagged. The CI sets it through --baseURL, from
 # params.plot.version below. This default is the same build.
-baseURL: "https://go-plot.github.io/docs/0.1/"
+baseURL: "https://go-plot.github.io/docs/0.2/"
 title: "go-plot"
 # themes/hextra is the tannevaled/hextra fork, pinned at a release tag:
 # upstream Hextra plus opt-in features (partial menu items, combos,
@@ -90,7 +90,7 @@ params:
   # documentation's version label (v0.1.2 -> 0.1): the CI reads it here.
   # The figures/ module requires the same version: the CI checks they agree.
   plot:
-    version: "v0.1.0"
+    version: "v0.2.0"
   versions:
     # The version selector shows "main" with the development icon.
     development: "main"