Documenter

[rofinn]

Moved docs over to Documenter.jl which mostly involved converting the restructured text to markdown and moving most of the docs into docstrings. Unfortunately, I needed to create some extra methods for the general docstrings, but I'm open to suggestions.

Fixes #629

[rofinn]

NOTE: The builds are failing on nightly because of the FFTW change, as has been noted elsewhere.

[ararslan]

For whatever reason, the mu and sigma don't seem to be getting rendered properly when I build the docs locally; they show up as mu and Sigma.

[rofinn]

Hmmm, I'm not seeing that here, but looks like I did forget a couple extra backslashes on MvNormalCanon.

[ararslan]

Some parts of the documentation are a little weird, I'm realizing, but that's unrelated to switching things over to Documenter and generally to the changes here. Improving the documentation is something else entirely. Thanks again for taking this on. I admit I didn't look at this too closely but I built the docs locally and they look good.

I am seeing some warnings when I build locally though:

Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
 > checking for missing docstrings.
 !! 12 docstrings potentially missing:

    Distributions.location :: Union{Tuple{D}, Tuple{Type{D},Symbol,AbstractArray{T,1} where T,AbstractArray{T,2} where T}} where D<:Distributions.AbstractMvLogNormal
    StatsBase.kurtosis :: Tuple{Distributions.Distribution,Bool}
    Distributions.MixtureModel :: Union{Tuple{Array{C,1}}, Tuple{C}} where C<:Distributions.Distribution
    Distributions.MixtureModel :: Union{Tuple{C}, Tuple{Type{C},AbstractArray}} where C<:Distributions.Distribution
    Distributions
    Distributions.insupport :: Union{Tuple{D}, Tuple{Union{D, Type{D}},AbstractArray}} where D<:(Distributions.Distribution{Distributions.Multivariate,S} where S<:Distributions.ValueSupport)
    Distributions.insupport :: Union{Tuple{D}, Tuple{Union{D, Type{D}},Any}} where D<:(Distributions.Distribution{Distributions.Univariate,S} where S<:Distributions.ValueSupport)
    Distributions.scale :: Union{Tuple{D}, Tuple{Type{D},Symbol,AbstractArray{T,1} where T,AbstractArray{T,2} where T}} where D<:Distributions.AbstractMvLogNormal
    StatsBase.entropy :: Tuple{Distributions.Distribution{Distributions.Multivariate,S} where S<:Distributions.ValueSupport,Real}
    StatsBase.entropy :: Tuple{Distributions.Distribution{Distributions.Univariate,S} where S<:Distributions.ValueSupport,Real}
    Distributions.logpdf :: Union{Tuple{Distributions.Distribution{Distributions.Matrixvariate,S} where S<:Distributions.ValueSupport,AbstractArray{T,2}}, Tuple{T}} where T<:Real
    StatsBase.params! :: Union{Tuple{D}, Tuple{Type{D},AbstractArray{T,1} where T,AbstractArray{T,2} where T,AbstractArray{T,1} where T,AbstractArray{T,2} where T}} where D<:Distributions.AbstractMvLogNormal

 > running doctests.
 > checking footnote links.
Documenter: populating indices.
Documenter: rendering document.
 !! Invalid local link: unresolved path
    ':func:`Gamma`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Beta`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Chisq`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Normal`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Gamma`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Chisq`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Gamma`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Normal`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Normal`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Normal`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Binomial`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Beta`' in univariate.md
 !! Invalid local link: unresolved path
    ':func:`Poisson`' in univariate.md
Documenter: skipping docs deployment.
  You can set DOCUMENTER_DEBUG to "true" in Travis to see more information.

I guess some broken links?

[rofinn]

Looks like I missed the broken links in the existing docstrings cause I was running an outdated version of documenter (0.10.0 vs 0.11.1).

[rofinn]

I'll probably open a separate issue for improving the documentation once we finish making the switch to documenter. I don't have strong views on how the documentation should be organized or written, but I did notice some undocumented functionality that I'd like to fix in a separate PR.

[ararslan]

Thanks so much for all your hard work here!

[ararslan]

Looks like for things to work on 0.7, you'll need to fix the invalid escape sequences in the docstrings. That is, all of the single LaTeX backslashes will need to be escaped. Looks like you've gotten a lot of them, but a few still lurk. Also we'll need to use Documenter inline math (``) rather than LaTeX inline math ($).

[ararslan]

The \mu here needs to be \\mu

[ararslan]

Looks like there are still a couple more invalid escape sequences, e.g. in VonMises

Edit: Pushed a commit to fix the ones I found

[ararslan]

Awesome, all of the escape failures seem to be fixed, so now the nightly failure is due to FFT stuff, which should be fixed in #641.

[ararslan]

Should be squashed on merge

[rofinn]

Awesome, thanks @ararslan!

[ararslan]

Thank you! This is no small task and your efforts here are much appreciated.

[ararslan]

Sorry for all the closing and opening. Travis uses the merge commit so closing and reopening is like rebasing Travis for a new run but much, much lazier.

[rofinn]

Looks like there are still precision issues with PoissonBinomial on nightly which I guess weren't completely fixed with #642?

[ararslan]

Yeah, will be fixed by #643.

[rofinn]

Even if the tests pass this time around we shouldn't merge this yet. I'll need to modify the docstring that was edited in #644 so that the equations are displayed in Documenter correctly.

[ararslan]

Right, I just wanted to make sure the tests pass.

[mschauer]

Sorry for the side-effect, @rofinn . By the way, does the statement from the julia docs (still) hold that unicode greek letters are in general preferred over latex greek command in docstrings?

Use Unicode characters rather than their LaTeX escape sequence, i.e. α = 1 rather than \\alpha = 1.

[rofinn]

@mschauer No problem, just wanted to make sure this didn't get merged prematurely. Yeah, looks like that preference still holds and most of the time I don't think it'll cause problems with documenter, but it looks like some characters are rendered differently. I'm inclined to leave updating the latex escape sequences to other PRs though.

[mschauer]

Good, good.

[ararslan]

Ahhhh it's so amazing to see green CI on nightly again. :D Thanks again to everyone involved!

[rofinn]

Ok, just needed a single line change. Assuming, the build passes (tests passed on 0.6 and 0.7 locally) this should be good to merge.

[ararslan]

Thanks so much again! This is great.