set up documentation using Documenter.jl (#4)

Enable citations in docs using DocumenterCitations.jl

add separate Project.toml file for docs

.gitignore

@@ -1 +1,2 @@
-/Manifest.toml
+**Manifest.toml
+docs/build

docs/LatSpec.bib

@@ -0,0 +1,10 @@
+@book{Gattringer/Lang,
+    author = {Gattringer/Lang},
+    title = {Quantum chromodynamics on the lattice},
+    doi = {10.1007/978-3-642-01850-3},
+    isbn = {978-3-642-01849-7},
+    publisher = {Springer},
+    address = {Berlin},
+    volume = {788},
+    year = {2010}
+}

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+LatSpec = "5648dd92-b909-466b-b6bb-bca0d81a8536"

docs/make.jl

@@ -0,0 +1,14 @@
+using Documenter
+using DocumenterCitations
+using LatSpec
+
+bib = CitationBibliography("LatSpec.bib")
+makedocs(
+    bib,
+    sitename="LatSpec.jl",
+    pages = [
+        "Home"       => "index.md",
+        "References" => "references.md"
+    ],
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true")
+)

docs/src/index.md

@@ -0,0 +1,10 @@
+# LatSpec.jl Documentation
+
+```@meta
+CurrentModule = LatSpec
+```
+
+```@docs
+autocor
+autotimeexp
+```

docs/src/references.md

@@ -0,0 +1,2 @@
+```@bibliography
+```

src/statistics.jl

@@ -1,28 +1,46 @@
-# Autocorrelation for a specifig lag
-function autocor(x::AbstractVector, lag::Integer)
+"""
+    autocor(x,lag)
+
+Returns autocorrelation function for a distance of lag, i.e. between values of
+```x[t]``` and ```x[t+lag]```. The autocorrelation function is normalized such
+that ```autocor(x,0) = 1```. This is equvivalent to the quantity
+``\\Gamma_X(t)`` of equation (4.61) in [GattringerLang](@cite).
+"""
+function autocor(x, lag)
     # (wasteful in terms of allocations but clear)
     z = x .- mean(x)
     a = sum(z[1+lag:end].*z[1:end-lag])/sum(z.*z)
     return a
 end
-# Autocorrelation for a automatically choosen number of lags
+"""
+    autocor(x)
+
+Returns autocorrelation function for a set of lags from ``0`` up to the closest
+integer to ``10 \\text{log}_{10}(l)``. Here ``l`` is the number of elements in
+```x```.
+"""
 function autocor(x)
     lx   = length(x)
-    # heuristic for choosing a suitable number of lags
     lags = collect(0:min(lx-1, round(Int,10*log10(lx))))
     a = zeros(eltype(x),length(lags))
     for i in 1:length(lags)
         a[i] = autocor(x, lags[i])
     end
     return a
 end
-# Perform exponential fit of autocorrelation and extract characteristic time
+"""
+    autotimeexp(x)
+
+Returns ``\\max(1,\\tau)`` where ``\\tau`` is the exponential autocorrelation
+time of a series of measurements ``x``. This is obtained by fitting the
+autocorrelation function to an exponential function of the form
+``A \\exp(\\frac{t}{\\tau})``.
+"""
 function autotimeexp(O)
     a = autocor(O)
     @. modelτ(x,p) = abs.(p[2])*exp(-x/p[1])
     x = collect(1:length(a))
     c = curve_fit(modelτ, x, a, ones(2))
     τ = c.param[1]
-    # if autocorrelation time τ is smaller than 1 return just 1
     return max(one(τ),τ)
 end