From 18ae5a913a3f5f48a928d4b2387614758ba05357 Mon Sep 17 00:00:00 2001
From: Oliver Schulz <oschulz@mpp.mpg.de>
Date: Mon, 2 Dec 2019 01:33:50 -0800
Subject: [PATCH] Add docs

---
 README.md             |  4 ++++
 docs/src/index.md     | 47 +++++++++++++++++++++++++++++++++++++++++++
 src/mv_binned_dist.jl | 11 ++++++++++
 src/uv_binned_dist.jl | 10 +++++++++
 4 files changed, 72 insertions(+)

diff --git a/README.md b/README.md
index be1880b..be3b8c5 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,10 @@
 [![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/github/oschulz/EmpiricalDistributions.jl?branch=master&svg=true)](https://ci.appveyor.com/project/oschulz/EmpiricalDistributions-jl)
 [![Codecov](https://codecov.io/gh/oschulz/EmpiricalDistributions.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/oschulz/EmpiricalDistributions.jl)
 
+A Julia package for empirical probability distributions. Currently
+implements uni- and multivariate binned distributions, backed by
+[StatsBase.jl](https://github.com/JuliaStats/StatsBase.jl) histograms.
+
 
 ## Documentation
 
diff --git a/docs/src/index.md b/docs/src/index.md
index d60ff37..3bea2ce 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1 +1,48 @@
 # EmpiricalDistributions.jl
+
+A Julia package for empirical probability distributions that implement the
+[Distributions.jl](https://github.com/JuliaStats/Distributions.jl) API.
+
+This package currently provides uni- and multivariate binned distributions,
+backed by [StatsBase.jl](https://github.com/JuliaStats/StatsBase.jl)
+histograms.
+
+[`UvBinnedDist`](@ref) wraps a 1-dimensional histogram and presents it as
+a (binned) univariate continuous distribution:
+
+```julia
+using Distributions, StatsBase
+
+X_uv = rand(Normal(2.0, 0.5), 10^5)
+uvhist = fit(Histogram, X_uv)
+
+using EmpiricalDistributions
+
+uvdist = UvBinnedDist(uvhist)
+uvdist isa Distribution{Univariate,Continuous}
+```
+
+The resulting distribution can be queried, used to generate random numbers,
+etc.:
+
+```julia
+mean(uvdist), var(uvdist)
+maximum(uvdist), minimum(uvdist)
+rand(uvdist, 5)
+```
+
+[`MvBinnedDist`](@ref) does the same for a multi-dimensional histogram,
+and presents it as a (binned) multivariate continuous distribution:
+
+```julia
+X_mv = rand(MvNormal([3.5, 0.5], [2.0 0.5; 0.5 1.0]), 10^5)
+mvhist = fit(Histogram, (X_mv[1, :], X_mv[2, :]))
+
+using Distributions, EmpiricalDistributions
+
+mvdist = MvBinnedDist(mvhist)
+mvdist isa Distribution{Multivariate,Continuous}
+
+mean(mvdist), cov(mvdist)
+rand(mvdist, 5)
+```
diff --git a/src/mv_binned_dist.jl b/src/mv_binned_dist.jl
index 7fa14a2..9d7d9da 100644
--- a/src/mv_binned_dist.jl
+++ b/src/mv_binned_dist.jl
@@ -1,5 +1,16 @@
 # This file is a part of EmpiricalDistributions.jl, licensed under the MIT License (MIT).
 
+
+"""
+    UvBinnedDist <: Distribution{Univariate,Continuous}
+
+Wraps a multi-dimensional histograms and presents it as a binned multivariate
+distribution.
+
+Constructor:
+
+    MvBinnedDist(h::Histogram{<:Real,N})
+"""
 struct MvBinnedDist{T, N} <: Distributions.Distribution{Multivariate,Continuous}
     h::StatsBase.Histogram{<:Real, N}
     edges::NTuple{N, <:AbstractVector{T}}
diff --git a/src/uv_binned_dist.jl b/src/uv_binned_dist.jl
index c1d7d54..104cc95 100644
--- a/src/uv_binned_dist.jl
+++ b/src/uv_binned_dist.jl
@@ -1,6 +1,16 @@
 # This file is a part of EmpiricalDistributions.jl, licensed under the MIT License (MIT).
 
 
+"""
+    UvBinnedDist <: Distribution{Univariate,Continuous}
+
+Wraps a 1-dimensional histograms and presents it as a binned univariate
+distribution.
+
+Constructor:
+
+    UvBinnedDist(h::Histogram{<:Real,1})
+"""
 struct UvBinnedDist{T <: AbstractFloat} <: Distribution{Univariate,Continuous}
     h::Histogram{<:Real, 1}
     inv_weights::Vector{T}