General documentation for JuliaGaussianProcesses

[theogf]

Following the discussion in JuliaGaussianProcesses/KernelFunctions.jl#133 , we propose to create common website to contain the documentation from KernelFunctions.jl, AbstractGPs.jl, LatentGPs.jl and further packages to come.
Here is a place to discuss of the form that this website should take and what tools should be used.

Some propositions are to rely on Documenter.jl and combine it with Literate.jl or Franklin.jl.

[devmotion]

I would assume that the most straightforward approach would be to go with Documenter (and add Literate afterwards if we want to include longer notebook-like use cases). If we want to have a webpage that is not limited by Documenter's structure and it's supposed to be not "just" documentation, then I'd pick Franklin and choose one of the default templates.

[theogf]

I would assume that the most straightforward approach would be to go with Documenter (and add Literate afterwards if we want to include longer notebook-like use cases). If we want to have a webpage that is not limited by Documenter's structure and it's supposed to be not "just" documentation, then I'd pick Franklin and choose one of the default templates.

I would personally prefer something different from the usual Documenter structure. I find it quite refreshing when docs have a different structure.
Especially as we might aim at a more general structure
How about using https://tlienart.github.io/PkgPage.jl/ ?

[theogf]

I created https://github.com/JuliaGaussianProcesses/JuliaGaussianProcesses.github.io as a starting point

[sharanry]

I too feel Documenter.jl is limited in flexibility and a bit mundane. I am also facing a lot of issues with Documenter.jl in automatically generating notebooks in JuliaGaussianProcesses/AbstractGPs.jl#10. Using PkgPage.jl along with Franklin.jl in general seems like a great option.

Having a common website should enable us to have unified documentation and example notebooks show casing how to use them together. Regarding the general structure of the the documentation, we could have subsections for each package for API related documentation, but have common "getting started" guides and tutorials. Turing's documentation structure could serve as a great reference.

[devmotion]

Yeah, Documenter is really just for documenting packages and showing some examples. It's good at what it aims to do, but it's not a fancy webpage. I really don't think we should use the same setup as the Turing webpage though. PkgPage looks great 👍 I think I would prefer such a Franklin-based solution.

[devmotion]

I am also facing a lot of issues with Documenter.jl in automatically generating notebooks in JuliaGaussianProcesses/AbstractGPs.jl#10.

I'm not sure why that's the case though, it works quite well for other packages?

[sharanry]

I'm not sure why that's the case though, it works quite well for other packages?

It seems to work for Literate.jl package's documentation. It has been difficult to debug as there are no helpful error messages as such. Even in the build logs.

Also, now that we are aiming for a unified documentation, is it right to assume the examples described in JuliaGaussianProcesses/AbstractGPs.jl#10 would go to this website? If that's the case, the examples in JuliaGaussianProcesses/AbstractGPs.jl#10 would be executed using Franklin.jl?

[devmotion]

Also, now that we are aiming for a unified documentation, is it right to assume the examples described in JuliaGaussianProcesses/AbstractGPs.jl#10 would go to this website? If that's the case, the examples in JuliaGaussianProcesses/AbstractGPs.jl#10 would be executed using Franklin.jl?

I guess we might still want to use Literate to run it instead of just writing a webpage with Franklin since otherwise there's neither a Julia script nor a notebook version of the examples. IMO it would be really nice and probably helpful for users to keep these additional formats since it simplifies rerunning the examples.

[sharanry]

I created https://github.com/JuliaGaussianProcesses/JuliaGaussianProcesses.github.io as a starting point

@theogf If it is okay with you, I will initialize this project with PkgPage.jl. :) Please let me know.

[theogf]

Oh I did already actually! But I did not add anything so far, and I did not manage to make it work yet. But you are free to try, I don't have so much free time these days

[sharanry]

@thoegf I got the build to pass. There were some problems with the deploy key setup. It currently pushes to gh-pages branch. However, for <organisation>.github.io sites we can only deploy the site from the master branch.

[sharanry]

https://juliagaussianprocesses.github.io/ loads successfully now.

GitHub requires us to deploy to master branch for org sites. So I have made changes to DeployPage.yml to build from dev and deploy to master as described in https://franklinjl.org/workflow/deploy/#synchronise_your_local_folder_userorg_website.

I have also changed the default branch to dev for easy access to the files(not the deploy files).

[theogf]

I think I will try to create a basic structure during this Christmas vacations, I will keep you updated with what I get :)

[theogf]

PR is here : #2, one of the first realisation is that PkgPage.jl was the wrong choice as it only allows for one page. I will try to correct that and add a method to preview the resulting website from a PR.