Structure pkgdown site and address parsing error

[pat-s]

Currently the pkgdown site cannot be built because of the following parsing error

Warning: Warning: Failed to parse usage:

S3method(`warp`, ``function``)(x, warper, ...)

This is because of

wiml/R/warp-unwarp.R

Line 121 in 5d3d436

warp.function <- function (x, warper, ...)

as it gets interpreted as a S3 method of warp, yet function is a reserved word.
I've renamed the function to warp_function() instead to solve the conflict.

In addition I've taken best efforts to structure the pkgdown reference in meaningful categories and did some small formatting changes to the vignette.

Also, to get documentation content of S3 methods into ?warp, they need to be defined in the method definition itself, i.e. in warp - child methods only need to have #' @export defined.

The ### Permutation variable importance header was defined twice, hence I removed one.

[alexanderbrenning]

Thanks @pat-s for looking into this - warp.function was of course meant to be a method for objects of class function, just like there's a print method print.function for functions, so there must be a way to get this into pkgdown. I wouldn't want warp_function to be just another regular function. There must be a different way of fixing this... I'll try to find an example from a different package...

[pat-s]

AFAICS the issue is that roxygen2 can't handle the syntax - see also r-lib/roxygen2#906.
It was supposed to be fixed in 2019 but maybe it popped up again? Maybe a follow-up in this issue could help.

I haven't seen the approach of a .function S3 method yet, so this was kind of new to me.

I've renamed it in this PR as your file comments indicated that you might not want to include it eventually and it got the build fixed - if there's a better way to do it, even better :)

[alexanderbrenning]

I don't think it's a roxygen2 problem since devtools::document() never reported any problems. I had been using this all the time. But yeah maybe a pragmatic solution will be fine, I'll probably change it to warp_[unfitted_]model then (because it's an unfitted model and there's already a warp_fitted_model).