Add workflow to update PRs with docs preview link in description

[mfisher87]

This improves accessibility by removing the need to know in advance where to find the ReadTheDocs link in the GitHub PR interface.

See demo: mfisher87#11 (the link doesn't work because RTD isn't set up for my fork ;) )

[jrbourbeau]

Thanks @mfisher87!

I'm curious if this a problem that has happened in a wild a few times? My gut reaction is to just point folks to the existing RTD PR build link instead of leaving a comment on every PR. Though, to be clear, if this is a common problem that would make life easier for lots of folks, then adding automation is fine (just wanting to avoid adding extra infrastructure if what we already have is reasonably sufficient)

[mfisher87]

instead of leaving a comment on every PR

To clarify, this edits the description of the PR, doesn't add a comment :)

[jrbourbeau]

To clarify, this edits the description of the PR, doesn't add a comment :)

Ah, great. I think that's better than a comment. I'm still curious about how widespread of an issue we think this is.

[mfisher87]

I'm still curious about how widespread of an issue we think this is.

Speaking only for myself, I see it as a widespread issue that many of us, including myself, are blind to until we encounter someone who's been contributing for a while but has no idea PR previews have been there all along. I would describe the group impacted as "all users with no (or trivial) prior experience with either GitHub or ReadTheDocs", which is a huge group!

This user persona has no way to know:

1. There is a PR preview at all

2. That the PR preview is under the "show all checks" interface item. Building a documentation preview is not a "check":

   

3. That "details" link will take you to the PR preview or that "ReadTheDocs build succeeded" means a build just for my PR succeeded and is live on the internet. With all the context around "checks" this could be interpreted as a dry-run/test build only:

   

All of this language actually misdirects a user seeking a preview away from clicking on it! 😓

I think many potential future contributors are members of science communities who are undergoing transitions towards working in open source, and have little experience with the tools that feel like turning on a faucet to me (us) after using them for so long. If we can lower the barriers to bringing them on to our ways of working, it will be easier to see the path to adoption, and the slow march towards more open and reproducible science takes another step ;)

[jhkennedy]

I'd be in favor of this! It definitely simplifies getting to the preview, and while ReadTheDocs is frequently used, there are a lot of projects that instead use CircleCI asset previews or just publish to github.io, so I do not expect all/most users just to know how to get the docs preview.

[mfisher87]

pre-commit.ci autofix

GitHub prevented pre-commit.ci from autofixing this pr due to autofixes to a workflow file

Interesting... I'll have to come back to this.

[jrbourbeau]

I'd be in favor of this!

Cool -- glad to hear there are multiple people that would find this useful. I mostly just wanted to raise the point that there's a maintenance cost associated with adding automation like this, and maintainer time is often hard to come by, so it's good to be thoughtful before taking that additional maintenance cost on. It sounds like you both have been thoughtful (not surprising), so feel free to go for it 👍

[mfisher87]

Thanks James! I agree it's very important to be careful with maintenance burden, and I really appreciate having a team that helps me check my biases :) When something sounds like a good idea, I think we're all vulnerable, at least a little bit, to underestimating the costs.