Fix README.md and add a few more doctests (#272)

* Various fixes

* Change documenter output

* Remove kommas

* Change jldoctest to julia

README.md

@@ -14,7 +14,7 @@ using StatsPlots
 
 plot(chn)
 ```
-![Basic plot for Chains](https://TuringLang.github.io/MCMCChains.jl/dev/default_plot.png)
+![Basic plot for Chains](https://turinglang.github.io/MCMCChains.jl/dev/default_plot.svg)
 
 See the [docs](https://TuringLang.github.io/MCMCChains.jl/dev/) for more information.
 

docs/src/getting-started.md

@@ -25,7 +25,7 @@ val = rand(500, 2, 3)
 chn = Chains(val, [:a, :b])
 ```
 
-By default, parameters will be given the name "param_i", where *i* is the parameter
+By default, parameters will be given the name `param_i`, where `i` is the parameter
 number:
 
 ```@example index
@@ -55,7 +55,7 @@ replacenames
 
 Chains parameters are sorted into sections that represent groups of parameters, see 
 [`MCMCChains.group`](@ref).
-By default, every chain contains a `:parameters` section, to which all unassigned parameters are
+By default, every chain contains a `parameters` section, to which all unassigned parameters are
 assigned to. Chains can be assigned a named map during construction:
 
 ```@example index

src/chains.jl

@@ -191,11 +191,18 @@ names as the values.
 
 Passing `flatten=true` will return a `NamedTuple` with keys ungrouped.
 
-Example:
-
+# Example
 ```julia
-x = get(c, :param_1)
-x = get(c, [:param_1, :param_2])
+julia> chn = Chains([1:5 6:10]);
+
+julia> get(chn, :param_1)
+(param_1 = [1; 2; … ; 4; 5],)
+
+julia> get(chn, [:param_1, :param_2])
+(param_2 = [6; 7; … ; 9; 10], param_1 = [1; 2; … ; 4; 5])
+
+julia> get(chn, :param_1; flatten=true)
+(param_1 = 1,)
 ```
 """
 Base.get(c::Chains, v::Symbol; flatten = false) = get(c, [v], flatten=flatten)
@@ -231,11 +238,15 @@ Return all parameters in a given section(s) as a `NamedTuple`.
 
 Passing `flatten=true` will return a `NamedTuple` with keys ungrouped.
 
-Example:
-
+# Example
 ```julia
-x = get(chn, section = :parameters)
-x = get(chn, section = [:internals, :parameters])
+julia> chn = Chains([1:5 6:10], [:a, :b], Dict(:internals => [:a]));
+
+julia> x = get(chn; section=:parameters)
+(b = [6; 7; … ; 9; 10],)
+
+julia> x = get(chn; section=[:internals, :parameters])
+(a = [1; 2; … ; 4; 5], b = [6; 7; … ; 9; 10])
 ```
 """
 function Base.get(
@@ -272,11 +283,22 @@ in their name (as in "P[1]") will be grouped into the returned value as P.
 
 Passing `flatten=true` will return a `NamedTuple` with keys ungrouped.
 
-Example:
-
+# Example
 ```julia
-x = get_params(chn)
-x.P
+julia> chn = Chains(1:5);
+
+julia> x = get_params(chn);
+
+julia> x.param_1
+2-dimensional AxisArray{Int64,2,...} with axes:
+    :iter, 1:1:5
+    :chain, 1:1
+And data, a 5×1 Array{Int64,2}:
+ 1
+ 2
+ 3
+ 4
+ 5
 ```
 """
 get_params(c::Chains; flatten = false) = get(c, section = sections(c), flatten=flatten)
@@ -406,8 +428,7 @@ Return a string containing summary information for a `Chains` object.
 If the `section` keyword is used, this function prints only the relevant section
 header.
 
-Example:
-
+# Example
 ```julia
 # Printing the whole header.
 header(chn)
@@ -519,8 +540,7 @@ end
 
 Return a new `Chains` object with a `NamedTuple` type `n` placed in the `info` field.
 
-Example:
-
+# Example
 ```julia
 new_chn = setinfo(chn, NamedTuple{(:a, :b)}((1, 2)))
 ```

src/rstar.jl

@@ -2,16 +2,14 @@
     rstar([rng ,]classif::Supervised, chains::Chains; kwargs...)
     rstar([rng ,]classif::Supervised, x::AbstractMatrix, y::AbstractVector; kwargs...)
 
-Compute the R* convergence diagnostic of MCMC.
+Compute the ``R^*`` convergence diagnostic of MCMC.
 
 This implementation is an adaption of Algorithm 1 & 2, described by [^LambertVehtari2020].
 Note that the correctness of the statistic depends on the convergence of the classifier used
 internally in the statistic. You can inspect the training of the classifier by adjusting the
 verbosity level.
 
-[^LambertVehtari2020]: Lambert & Vehtari (2020). ``R^*``: A robust MCMC convergence diagnostic
-with uncertainty using gradient-boosted machines. arXiv preprint
-<https://arxiv.org/abs/2003.07900>.
+[^LambertVehtari2020]: Lambert & Vehtari (2020). ``R^*``: A robust MCMC convergence diagnostic with uncertainty using gradient-boosted machines. arXiv preprint <https://arxiv.org/abs/2003.07900>.
 
 # Keyword Arguments
 * `subset = 0.8` ... Subset used to train the classifier, i.e. 0.8 implies 80% of the samples are used.