Add better/more thorough documentation (#41)

* Move reference to API; add proper intro page and glossary/concepts explanation

* Add how-to placeholder file

* Fix/separate PR contents

* Attempt to fix docs previews

* Add more examples and info to the front page

* Fix Plots GR warning during build docs

* Tweak signal gen for plot

* Improve language clarity and add rolling peak finding animation

* untested fix for bad header link gen

* Better heading links

* More writing improvements; move plotting to their own scripts; add animation for prominence

* fix footnote

* Simplify curve formula

* Simplify pkg add peaks output example code

* Add more explanations and improve phrasing

* Move example plots boilerplate to file (DRY)

* Update pkgs

* Reduce glossary page size by removing redundant info in plot

* Add missing standards file

* Add plotlybase to docs env

* Tweak width plot

* Update main page slightly

* More main page improvements; added links to Base Julia docs where relevant

* Add how-to section

* Update README [skip ci]

.github/workflows/CI.yml

@@ -44,6 +44,10 @@ jobs:
   docs:
     name: Documentation
     runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Required when authenticating with `GITHUB_TOKEN`, not needed when authenticating with SSH deploy keys
+      pull-requests: read  # Required when using `push_preview=true`
+      statuses: write  # Optional, used to report documentation build statuses
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1

README.md

@@ -8,68 +8,17 @@
 [![codecov](https://codecov.io/gh/halleysfifthinc/Peaks.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/halleysfifthinc/Peaks.jl)
 [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 
-Peaks.jl contains peak (local extrema) finding functions for vector data. Contributions welcome.
+Peaks.jl contains peak (local extrema) finding functions for vector data. Visit the documentation for a complete introduction, how-to guide, and reference. Contributions welcome.
 
 [![signal-with-peaks-prominences-and-widths](docs/src/assets/images/maxima_prom_width.png)](#)
 
-```julia
-julia> using Peaks
-
-julia> t = 0:1/100:1;
-
-julia> y = 2*sin.(5*t)+3*sin.(10*t)+2*sin.(30*t);
-
-julia> pks, vals = findmaxima(y)
-([8, 26, 48, 70, 88], [4.344867409921723, 5.5693856245725195, 0.42179571038522123, 3.050541716751975,
-1.765468536605815])
-
-julia> pks, proms = peakproms(pks, y)
-([8, 26, 48, 70, 88], [1.9441651653930858, 5.5693856245725195, 2.203426259167901, 6.0957723300230855,
-2.195991801053836])
-
-julia> pks, widths, leftedge, rightedge = peakwidths(pks, y, proms)
-([8, 26, 48, 70, 88], [7.168551512183585, 13.02544712081329, 8.262715646139178, 13.80559202119737,
-7.663187146933097], [4.916043956211862, 18.50125024651451, 43.35170982447645, 63.83409366134414, 84.28425741824285],
-[12.084595468395447, 31.5266973673278, 51.61442547061563, 77.63968568254151, 91.94744456517594])
-
-julia> _, proms = peakproms!(pks, y; minprom=1)
-([8, 26, 48, 70, 88], [1.9441651653930858, 5.5693856245725195, 2.203426259167901, 6.0957723300230855, 2.195991801053836])
-
-julia> using Plots
-julia> plotpeaks(t, y, peaks=pks, prominences=true, widths=true)  # see above plot for result
-```
-
 ## Features
 
-- Find peaks (maxima or minima), peak prominence, and peak width
-    - Filter peaks by peak spacing (window size), prominence, and width
-    - Compute "Full Width Half Maximum" (FWHM) of discrete or sampled functions using `peakwidths`
+- Find peak (maxima or minima) locations, height, prominence, and width
+    - Filter peaks by peak spacing (window size), height, prominence, and width (including "Full Width Half Maximum (FWHM)")
 - Fully supports `NaN`/`missing` with optional tolerance using keyword arg `strict`:
     - Conventional handling/propagation of `NaN`/`missing` when `strict = true` (the default)
-      ```julia
-      julia> argmaxima([missing,2,0,1,1,0]) # equivalent to [2,0,1,1,0]
-      1-element Vector{Int64}:
-       4
-
-      julia> peakproms([2,4], [NaN,2,0,1,1,0])
-      ([2, 4], [NaN, 1.0])
-
-      julia> peakwidths([2,4], [NaN,2,0,1,1,0], [2,1])
-      ([2, 4], [NaN, 2.0], [NaN, 3.5], [2.5, 5.5])
-      ```
     - Reasonable alternatives when `strict = false`
-      ```julia
-      julia> argmaxima([missing,2,0,1,1,0]; strict=false)
-      2-element Vector{Int64}:
-       2
-       4
-
-      julia> peakproms([2,4], [NaN,2,0,1,1,0]; strict=false)
-      ([2, 4], [2.0, 1.0])
-
-      julia> peakwidths([2,4], [NaN,2,0,1,1,0], [2,1]; strict=false)
-      ([2, 4], [1.5, 2.0], [1.0, 3.5], [2.5, 5.5])
-      ```
 
 ## Related