Some improvements to documentation

README.md

@@ -61,10 +61,9 @@ below.  Here we only give basic information.
 ### Documentation
 
 The complete manual of `LombScargle.jl` is available at
-http://lombscarglejl.readthedocs.io.  It has detailed explanation of all
+https://giordano.github.io/LombScargle.jl/stable/.  It has detailed explanation of all
 functions provided by the package and more examples than what you will find
-here, also with some plots.  You can also download the PDF version of the manual
-from https://media.readthedocs.org/pdf/lombscarglejl/latest/lombscarglejl.pdf.
+here, also with some plots.
 
 Installation
 ------------
@@ -122,7 +121,7 @@ If the signal has uncertainties, the `signal` vector can also be a vector of
 which case you need not to pass a separate `errors` vector for the uncertainties
 of the signal.  You can create arrays of `Measurement` objects with the
 `measurement` function, see `Measurements.jl` manual at
-http://measurementsjl.readthedocs.io/ for more details.
+https://juliaphysics.github.io/Measurements.jl/latest/ for more details.
 
 With the `LombScargle.plan` function you can pre-plan a periodogram and save
 time and memory for the actual computation of the periodogram.  See
@@ -235,10 +234,10 @@ Astropy Team.
 
 
 [docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg
-[docs-latest-url]: https://lombscarglejl.readthedocs.io/en/latest/
+[docs-latest-url]: https://giordano.github.io/LombScargle.jl/latest/
 
 [docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
-[docs-stable-url]: https://lombscarglejl.readthedocs.io/en/stable/
+[docs-stable-url]: https://giordano.github.io/LombScargle.jl/stable/
 
 [pkgeval-link]: http://pkg.julialang.org/?pkg=LombScargle
 

docs/src/index.md

@@ -211,8 +211,8 @@ actual computation of the periodogram (completely type-stable) makes overall
 computation faster than directly calling [`lombscargle`](@ref). Secondly, the
 `LombScargle.PeriodogramPlan` bears the time vector, but the quantities that are
 pre-computed in planning stage do not actually depend on it. This is
-particularly useful if you want to calculate the false-alarm probability via
-bootstrapping with [`LombScargle.bootstrap`](@ref) function: the vector time is
+particularly useful if you want to calculate the [False-Alarm Probability](@ref)
+via bootstrapping with [`LombScargle.bootstrap`](@ref): the vector time is
 randomly shuffled, but pre-computed quantities will remain the same, saving both
 time and memory in each iteration. In addition, you ensure that you will use the
 same options you used to compute the periodogram.
@@ -346,60 +346,45 @@ of observations.
 
 ### Access Frequency Grid and Power Spectrum of the Periodogram
 
+[`lombscargle`](@ref) returns a `LombScargle.Periodogram` object, but you most
+probably want to use the frequency grid and the power spectrum. You can access
+these vectors with `freq` and `power` functions, just like in `DSP.jl`
+package. If you want to get the 2-tuple `(freq(p), power(p))` use the
+`freqpower` function.
+
 ```@docs
 power
 freq
 freqpower
 ```
 
-[`lombscargle`](@ref) function returns a `LombScargle.Periodogram` object, but
-you most probably want to use the frequency grid and the power spectrum. You can
-access these vectors with `freq` and `power` functions, just like in `DSP.jl`
-package. If you want to get the 2-tuple `(freq(p), power(p))` use the
-`freqpower` function.
+### Access Period Grid
 
-### Access Periods and their and Power in the Periodogram
+The following utilities are the analogs of [`freq`](@ref) and
+[`freqpower`](@ref), but relative to the periods instead of the
+frequencies. Thus `period(p)` returns the vector of periods in the periodogram,
+that is `1./freq(p)`, and `periodpower(p)` gives you the 2-tuple `(period(p),
+power(p))`.
 
 ```@docs
 period
 periodpower
 ```
 
-These utilities are the analogs of [`freq`](@ref) and [`freqpower`](@ref), but
-relative to the periods instead of the frequencies. Thus `period(p)` returns the
-vector of periods in the periodogram, that is `1./freq(p)`, and `periodpower(p)`
-gives you the 2-tuple `(period(p), power(p))`.
-
 ### `findmaxpower`, `findmaxfreq`, and `findmaxperiod` Functions
 
+Once you compute the periodogram, you usually want to know which are the
+frequencies or periods with highest power. To do this, you can use the
+[`findmaxfreq`](@ref) and [`findmaxperiod`](@ref) functions.
+
 ```@docs
 findmaxpower
 findmaxfreq
 findmaxperiod
 ```
 
-Once you compute the periodogram, you usually want to know which are the
-frequencies or periods with highest power. To do this, you can use the
-[`findmaxfreq`](@ref) and [`findmaxperiod`](@ref) functions.  They return the
-vector of frequencies and periods, respectively, with the highest power in the
-periodogram `p`. If a scalar real argument `threshold` is provided, return the
-frequencies with power larger than or equal to `threshold`. If you want to limit
-the search to a narrower frequency or period range, pass as second argument a
-vector with the extrema of the interval.
-
-The value of the highest power of a periodogram can be calculated with the
-[`findmaxpower`](@ref) function.
-
 ### False-Alarm Probability
 
-```@docs
-prob(::LombScargle.Periodogram, ::Real)
-probinv(::LombScargle.Periodogram, ::Real)
-LombScargle.M
-fap(::LombScargle.Periodogram, ::Real)
-fapinv(::LombScargle.Periodogram, ::Real)
-```
-
 Noise in the data produce fluctuations in the periodogram that will present
 several local peaks, but not all of them related to real periodicities. The
 significance of the peaks can be tested by calculating the probability that its
@@ -420,6 +405,14 @@ whose first argument is the periodogram and the second one is the ``p_{0}``
 value. The function [`probinv`](@ref) is its inverse: it takes the probability
 as second argument and returns the corresponding ``p_{0}`` value.
 
+```@docs
+prob(::LombScargle.Periodogram, ::Real)
+probinv(::LombScargle.Periodogram, ::Real)
+LombScargle.M
+fap(::LombScargle.Periodogram, ::Real)
+fapinv(::LombScargle.Periodogram, ::Real)
+```
+
 Here are the probability functions for each normalization supported by
 `LombScargle.jl`:
 
@@ -479,19 +472,12 @@ larger than ``p_{0}`` indicates that a signal is likely present (see [CUM04]).
     is not completely reliable. A different approach to calculate the false-alarm
     probability is to perform Monte Carlo or bootstrap simulations in order to
     determine how often a certain power level ``p_{0}`` is exceeded just by chance
-    (see [CMB99], [CUM04], and [ZK09]). See next section.
-
+    (see [CMB99], [CUM04], and [ZK09]). See the [Bootstrapping](@ref) section.
 
 #### Bootstrapping
 
-```@docs
-LombScargle.bootstrap
-fap(::LombScargle.Bootstrap{<:AbstractFloat}, ::Real)
-fapinv(::LombScargle.Bootstrap{<:AbstractFloat}, ::Real)
-```
-
-One of the possible and most simple statistical methods that you can use to
-measure the false-alarm probability and its inverse is
+One of the possible and simplest statistical methods that you can use to measure
+the false-alarm probability and its inverse is
 [bootstrapping](https://en.wikipedia.org/wiki/Bootstrapping_%28statistics%29)
 (see section 4.2.2 of [MHC93]).
 
@@ -520,27 +506,24 @@ used to compute the Lomb--Scargle periodogram before.
 
 `LombScargle.jl` provides simple methods to perform such analysis. The
 [`LombScargle.bootstrap`](@ref) function allows you to create a bootstrap sample
-with `N` permutations of the original data. All the arguments after the first
-one are passed around to [`lombscargle`](@ref). The output is a
-`LombScargle.Bootstrap` object.
+with `N` permutations of the original data.
 
-You can also pass to [`LombScargle.bootstrap`](@ref) a pre-computed
-`LombScargle.PeriodogramPlan` as second argument (this method takes no other
-argument nor keyword). In this way you will be sure to use exactly the same
-options you used before for computing the periodogram with the same periodogram
-plan.
+```@docs
+LombScargle.bootstrap
+```
 
 The false-alarm probability and its inverse can be calculated with [`fap`](@ref)
 and [`fapinv`](@ref) functions respectively.  Their syntax is the same as the
 methods introduced above, but with a `LombScargle.Bootstrap` object as first
 argument, instead of the `LombScargle.Periodogram` one.
 
-### `LombScargle.model` Function
-
 ```@docs
-LombScargle.model
+fap(::LombScargle.Bootstrap{<:AbstractFloat}, ::Real)
+fapinv(::LombScargle.Bootstrap{<:AbstractFloat}, ::Real)
 ```
 
+### `LombScargle.model` Function
+
 For each frequency ``f`` (and hence for the corresponding angular frequency
 ``\omega = 2\pi f``) the Lomb--Scargle algorithm looks for the sinusoidal function
 of the type
@@ -588,32 +571,9 @@ This is what the [`LombScargle.model`](@ref) function does in order to return
 the best fitting Lomb--Scargle model for the given signal at the given
 frequency.
 
-Mandatory arguments are:
-
-- `times`: the observation times
-- `signal`: the signal, sampled at `times` (must have the same length
-  as `times`)
-- `frequency`: the frequency at which to calculate the model
-
-The optional arguments are:
-
-- `errors`: the vector of uncertainties of the signal. If provided, it must have
-  the same length as `signal` and `times`, and be the third argument. Like for
-  [`lombscargle`](@ref), if the signal has uncertainties, the `signal` vector
-  can also be a vector of `Measurement` objects, and this argument should be
-  omitted
-- `times_fit`: the vector of times at which the model will be calculated. It
-  defaults to `times`. If provided, it must come after `frequency`
-
-Optional boolean keywords `center_data` and `fit_mean` have the same meaning as
-in [`lombscargle`](@ref) function:
-
-- `fit_mean`: whether to fit for the mean. If this is `false`, like in the
-  original Lomb--Scargle periodogram, ``\mathbf{A}`` does not have the third
-  column of ones, ``c_f`` is set to ``0`` and the unknown vector to be determined
-  becomes ``x = [a_f, b_f]^\text{T}``
-- `center_data`: whether the data should be pre-centered before solving the
-  linear system. This is particularly important if `fit_mean=false`
+```@docs
+LombScargle.model
+```
 
 Examples
 --------

src/LombScargle.jl

@@ -79,7 +79,7 @@ lombscargle(args...; kwargs...) = lombscargle(plan(args...; kwargs...))
 
 """
     lombscargle(times::AbstractVector{<:Real}, signal::AbstractVector{<:Real},
-                errors::AbstractVector{<:Real}=ones(signal); keywords...)
+                [errors::AbstractVector{<:Real}]; keywords...)
 
 Compute the Lomb–Scargle periodogram of the `signal` vector, observed at
 `times`.  You can also specify the uncertainties for each signal point with

src/bootstrap.jl

@@ -34,7 +34,7 @@ bootstrap(N::Integer, t::AbstractVector{<:Real}, rest...; kwargs...) =
 
 Create `N` bootstrap samples, perform the Lomb–Scargle analysis on them, and
 store all the highest peaks for each one in a `LombScargle.Bootstrap` object.
-All the arguments after `N` are passed around to `lombscargle`, which see.
+All the arguments after `N` are passed around to [`lombscargle`](@ref).
 """
 bootstrap(::Integer, ::AbstractVector{<:Real})
 
@@ -44,7 +44,7 @@ bootstrap(::Integer, ::AbstractVector{<:Real})
 Create `N` bootstrap samples, perform the Lomb–Scargle analysis on them for the given
 `plan`, and store all the highest peaks for each one in a `LombScargle.Bootstrap` object.
 
-See documentation of `LombScargle.plan` for how to plan a Lomb–Scargle periodogram.
+See documentation of [`LombScargle.plan`](@ref) for how to plan a Lomb–Scargle periodogram.
 """
 bootstrap(::Integer, ::PeriodogramPlan)
 
@@ -53,7 +53,7 @@ bootstrap(::Integer, ::PeriodogramPlan)
 
 Return the false-alarm probability for `power` in the bootstrap sample `b`.
 
-Its inverse is the `fapinv` function.
+Its inverse is the [`fapinv`](@ref) function.
 """
 fap(b::Bootstrap{<:AbstractFloat}, power::Real) =
     length(find(x -> x >= power, b.p))/length(b.p)
@@ -69,7 +69,7 @@ determined with the bootstrap sample `b`.  In this case, you should enlarge your
 bootstrap sample so that `N*fap` can be rounded to an integer larger than or
 equal to 1.
 
-This is the inverse of `fap` function.
+This is the inverse of [`fap`](@ref) function.
 """
 fapinv(b::Bootstrap{<:AbstractFloat}, prob::Real) =
     get(b.p, round(Int, length(b.p)*prob), NaN)

src/planning.jl

@@ -145,7 +145,7 @@ plan(times::AbstractVector{<:Real}, signal::AbstractVector{<:Measurement}; kwarg
 
 """
     LombScargle.plan(times::AbstractVector{<:Real}, signal::AbstractVector{<:Real},
-                     errors::AbstractVector{<:Real}=ones(signal);
+                     [errors::AbstractVector{<:Real}];
                      normalization::Symbol=:standard,
                      noise_level::Real=1,
                      center_data::Bool=true,

src/utils.jl

@@ -95,7 +95,7 @@ periodpower(p::Periodogram) = (period(p), power(p))
 """
     findmaxperiod(p::Periodogram, [interval::AbstractVector{Real}], threshold::Real=findmaxpower(p))
 
-Return the array of period with the highest power in the periodogram `p`.  If a
+Return the array of periods with the highest power in the periodogram `p`.  If a
 scalar real argument `threshold` is provided, return the period with power
 larger than or equal to `threshold`.  If you want to limit the search to a
 narrower period range, pass as second argument a vector with the extrema of the
@@ -208,7 +208,7 @@ end
 
 Return the false-alarm probability for periodogram `P` and power value `pow`.
 
-Its inverse is the `fapinv` function.
+Its inverse is the [`fapinv`](@ref) function.
 """
 fap(P::Periodogram, pow::Real) = 1 - (1 - prob(P, pow))^M(P)
 
@@ -218,7 +218,7 @@ fap(P::Periodogram, pow::Real) = 1 - (1 - prob(P, pow))^M(P)
 Return the power value of the periodogram whose false-alarm probability is
 `prob`.
 
-This is the inverse of `fap` function.
+This is the inverse of [`fap`](@ref) function.
 """
 fapinv(P::Periodogram, prob::Real) = probinv(P, 1 - (1 - prob)^(inv(M(P))))
 
@@ -244,12 +244,23 @@ Mandatory arguments are:
 Optional arguments are:
 
 * `errors`: the vector of uncertainties of the signal.  If provided, it must
-  have the same length as `signal` and `times`, and be the third argument
+  have the same length as `signal` and `times`, and be the third argument.  Like
+  for [`lombscargle`](@ref), if the signal has uncertainties, the `signal`
+  vector can also be a vector of `Measurement` objects, and this argument should
+  be omitted
+
 * `times_fit`: the vector of times at which the model will be calculated.  It
   defaults to `times`.  If provided, it must come after `frequency`
 
 Optional keyword arguments `center_data` and `fit_mean` have the same meaning as
-in `lombscargle` function, which see.
+in [`lombscargle`](@ref):
+
+- `fit_mean`: whether to fit for the mean. If this is `false`, like in the
+  original Lomb--Scargle periodogram, ``\\mathbf{A}`` does not have the third
+  column of ones, ``c_f`` is set to ``0`` and the unknown vector to be determined
+  becomes ``x = [a_f, b_f]^\\text{T}``
+- `center_data`: whether the data should be pre-centered before solving the
+  linear system. This is particularly important if `fit_mean=false`
 """
 function model(t::AbstractVector{<:Real}, s::AbstractVector{T},
                errors::AbstractVector{<:Real}, f::Real,