add real docs

.github/workflows/Documentation.yml

@@ -0,0 +1,25 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

Project.toml

@@ -1,5 +1,6 @@
 name = "PoissonRandom"
 uuid = "e409e4f3-bfea-5376-8464-e040bb5c01ab"
+version = "0.4.1"
 
 [deps]
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"

README.md

@@ -1,7 +1,14 @@
-# PoissonRandom
+# PoissonRandom.jl: Fast Poisson Random Numbers
 
 [![Build Status](https://github.com/SciML/PoissonRandom.jl/workflows/CI/badge.svg)](https://github.com/SciML/PoissonRandom.jl/actions?query=workflow%3ACI)
 
+## Tutorials and Documentation
+
+For information on using the package,
+[see the stable documentation](https://poissonrandom.sciml.ai/stable/). Use the
+[in-development documentation](https://poissonrandom.sciml.ai/dev/) for the version of
+the documentation, which contains the unreleased features.
+
 ## Usage
 
 ```julia

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+PoissonRandom = "e409e4f3-bfea-5376-8464-e040bb5c01ab"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"

docs/make.jl

@@ -0,0 +1,19 @@
+using Documenter, PoissonRandom
+
+include("pages.jl")
+
+makedocs(
+    sitename="PoissonRandom.jl",
+    authors="Chris Rackauckas",
+    modules=[PoissonRandom],
+    clean=true,doctest=false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://poissonrandom.sciml.ai/stable/"),
+    pages=pages
+)
+
+deploydocs(
+   repo = "github.com/SciML/PoissonRandom.jl.git";
+   push_preview = true
+)

docs/pages.jl

@@ -0,0 +1,6 @@
+# Put in a separate page so it can be used by SciMLDocs.jl
+
+pages=[
+    "Home" => "index.md",
+    "pois_rand.md",
+]

docs/src/index.md

@@ -0,0 +1,97 @@
+# PoissonRandom.jl: Fast Poisson Random Numbers
+
+PoissonRandom.jl is a component of the SciML ecosystem which allows
+for fast generation of Poisson random numbers.
+
+## Installation
+
+To install ParameterizedFunctions.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("PoissonRandom")
+```
+
+## Usage
+
+```julia
+# Simple Poisson random
+pois_rand(λ)
+
+# Using another RNG
+using RandomNumbers
+rng = Xorshifts.Xoroshiro128Plus()
+pois_rand(rng,λ)
+```
+
+## Implementation
+
+It mixes two methods. A simple count method and a method from a normal approximation.
+See [this blog post for details](https://www.johndcook.com/blog/2010/06/14/generating-poisson-random-values/).
+
+## Benchmark
+
+```julia
+using RandomNumbers, Distributions, BenchmarkTools, StaticArrays,
+      RecursiveArrayTools, Plots, PoissonRandom
+labels = ["count_rand","ad_rand","pois_rand","Distributions.jl"]
+rng = Xorshifts.Xoroshiro128Plus()
+
+function n_count(rng,λ,n)
+  tmp = 0
+  for i in 1:n
+    tmp += PoissonRandom.count_rand(rng,λ)
+  end
+end
+
+function n_pois(rng,λ,n)
+  tmp = 0
+  for i in 1:n
+    tmp += pois_rand(rng,λ)
+  end
+end
+
+function n_ad(rng,λ,n)
+  tmp = 0
+  for i in 1:n
+    tmp += PoissonRandom.ad_rand(rng,λ)
+  end
+end
+
+function n_dist(λ,n)
+  tmp = 0
+  for i in 1:n
+    tmp += rand(Poisson(λ))
+  end
+end
+
+function time_λ(rng,λ,n)
+  t1 = @elapsed n_count(rng,λ,n)
+  t2 = @elapsed n_ad(rng,λ,n)
+  t3 = @elapsed n_pois(rng,λ,n)
+  t4 = @elapsed n_dist(λ,n)
+  @SArray [t1,t2,t3,t4]
+end
+
+# Compile
+time_λ(rng,5,5000000)
+# Run with a bunch of λ
+times = VectorOfArray([time_λ(rng,n,5000000) for n in 1:20])'
+plot(times,labels = labels, lw = 3)
+```
+
+![benchmark result](https://user-images.githubusercontent.com/1814174/40387004-1e377776-5dc0-11e8-88a2-2d9cb12db984.png)
+
+So this package ends up about 30% or so faster than Distributions.jl (the method
+at the far edge is λ-independent so that goes on forever).
+
+## Contributing
+
+- Please refer to the
+  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+  for guidance on PRs, issues, and other matters relating to contributing to SciML.
+- There are a few community forums:
+    - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
+    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
+    - on the [Julia Discourse forums](https://discourse.julialang.org)
+    - see also [SciML Community page](https://sciml.ai/community/)

docs/src/pois_rand.md

@@ -0,0 +1,5 @@
+# Poisson Random API
+
+```@docs
+pois_rand
+```

src/PoissonRandom.jl

@@ -141,6 +141,26 @@ function procf(λ, K::Int, s::Float64)
     return px,py,fx,fy
 end
 
+"""
+```julia
+pois_rand(λ)
+pois_rand(rng::AbstractRNG, λ)
+```
+
+Generates Poisson(λ) distributed random numbers using a fast polyalgorithm.
+
+## Examples
+
+```julia
+# Simple Poisson random
+pois_rand(λ)
+
+# Using another RNG
+using RandomNumbers
+rng = Xorshifts.Xoroshiro128Plus()
+pois_rand(rng,λ)
+```
+"""
 pois_rand(λ) = pois_rand(Random.GLOBAL_RNG, λ)
 pois_rand(rng::AbstractRNG, λ) = λ < 6 ? count_rand(rng, λ) : ad_rand(rng, λ)