Add GH action for commenting with link to docs preview

[theogf]

I thought it would be practical to automatically get a comment with a link to the preview of the docs.

[github-actions]

Once the build has completed, you can preview your PR at this URL: https://juliagaussianprocesses.github.io/KernelFunctions.jl/previews/PR227/

[willtebbutt]

Oooo I like this. In some ways it's a little redundant since, as @devmotion pointed out, you can just click on the Details of documenter/deploy, but for people who don't know about that it's way more explicit, and I don't think that you really lose anything.

[devmotion]

If we want to have a more prominent comment (I am not sure about this since the preview is already quite accessible) I think it would make more sense to add a final step to the documentation action. It seems a bit weird to just post a comment with the link, even it the build fails and the link is broken.

[theogf]

you can just click on the Details of documenter/deploy, but for people who don't know about that it's way more explicit, and I don't think that you really lose anything.

That's what I did for #225, but then I realised it's also pretty bothersome to go through all those clicks 😅
EDIT : Ah no I misunderstood the point, I actually went to the documentation build and found the link in there. It's true that you get to the docs in one click

@devmotion That's a good point. It's just going to be a bit more tricky:
The comment should only appear once, so we need to check when the docs build has succeeded for the first time. I have no idea how to verify this...

[devmotion]

@devmotion That's a good point. It's just going to be a bit more tricky:
The comment should only appear once, so we need to check when the docs build has succeeded for the first time. I have no idea how to verify this...

I imagined that there would a comment such as "Preview of documentation deployed: https://...." if it succeeds and "Preview of documentation could not be deployed" in the other case. One would have to rerun the action every time the documentation is built since otherwise you might check an outdated and incorrect preview.

[willtebbutt]

Alternatively, we could just always post a comment saying "click on the Details of the documentation/deploy action to see the most recent docs build" or something like that.

[devmotion]

One would have to rerun the action every time the documentation is built

But since this would lead to quite many comments I have even more doubts about this action than before.

[devmotion]

Alternatively, we could just always post a comment saying "click on the Details of the documentation/deploy action to see the most recent docs build" or something like that.

Hmm I'm not sure, I assumed the main intention of this PR was to reduce the number of clicks or lookups for getting to the preview build. I guess by now all contributors know how to access the preview, so I am not sure how helpful it would be to post this information in every PR 😉

[st--]

I guess by now all contributors know how to access the preview

I didn't before seeing this PR 😅
Though given that I know about it the documenter/deploy - Details link is sufficient.
I was just trying to see if the status notification can be changed from just "Documentation build succeeded" to "Documentation build succeeded - click on Details for preview"? 🤔 But I couldn't find what is it that adds that status.

[devmotion]

AFAICT Documenter.post_status which is called in lines such as https://github.com/JuliaDocs/Documenter.jl/blob/832f29b3f4c3057905f5232ecff8914955017fcc/src/Documenter.jl#L660 updates the status. It ends up calling https://github.com/JuliaDocs/Documenter.jl/blob/3430c65724870cfa461d8d3684f4d67bd2277c7e/src/deployconfig.jl#L468.

[st--]

Yeah that doesn't look like it's particularly trivial to change. How about simply adding a "contributing.md" that explicitly points out where to find the doc preview (can then also explain running JuliaFormatter, and anything else that'd be useful to make it easier for newcomers to start contributing)? Not sure how much work that'd be to make work here but I've also seen GitHub bots that post a comment when someone new to the repo opens their first PR, in which the bot can then point to contributing.md and/or explain the doc preview link?

[theogf]

Yeah that doesn't look like it's particularly trivial to change. How about simply adding a "contributing.md" that explicitly points out where to find the doc preview (can then also explain running JuliaFormatter, and anything else that'd be useful to make it easier for newcomers to start contributing)? Not sure how much work that'd be to make work here but I've also seen GitHub bots that post a comment when someone new to the repo opens their first PR, in which the bot can then point to contributing.md and/or explain the doc preview link?

"contributing.md" sounds like a good thing! Another option would be to put some of these info in a PR template?

[st--]

Another option would be to put some of these info in a PR template?

Oh yeah! I had thought of that when adding the formatter to the CI.

[theogf]

Should I just close this PR then?