Ability to render documentation for pull-requests

[jorgepiloto]

💡 Idea

When dependabot opens a pull-request, even if the doc-build job is passing, there is no way to visually check if documentations renders as expected unless you manually download the documentation-html artifacts.

Thus, I was thinking it may be interesting to add a new sub-directory inside the gh-pages/version/dev/pr/{id}.

The action should be smart enough to:

1. List all pull-request ids inside this directory
2. Remove outdated ones
3. Deploy the one linked to the pull-request

[RobPasMue]

Sounds great! We could even combine it with an automated comment on the PR that takes you to the dev version of the docs in your PR

[germa89]

Also, we should delete those PR build after the PR has been merged. I probably, another step should be added when pushing to main.

Would it be any issue of having multiple PRs writing to gh-pages? I'm thinking possible conflicts in big repositories where there is a lot of activity.

[germa89]

this seems useful: https://github.com/daiyi/gh-pages-pr-previews

[germa89]

Would it be any issue of having multiple PRs writing to gh-pages? I'm thinking possible conflicts in big repositories where there is a lot of activity.

One way to alleviate this might be to only deploy when some directories (doc or examples) are changed. We can use `git diff --exit-code path`` (https://stackoverflow.com/a/50117376/6650211).

[RobPasMue]

It's hard to tell whether only it should run with changes on those folders or not... I'm thinking about dependency bumps, I am also thinking about API changes, ... Not easy to tell when to publish or not. It should be up to each library to decide honestly. We should just provide the feature with this action to publish them.

this seems useful: https://github.com/daiyi/gh-pages-pr-previews

And I like this approach as well. It is similar to what @jorgepiloto proposes.

[RobPasMue]

Would it be any issue of having multiple PRs writing to gh-pages? I'm thinking possible conflicts in big repositories where there is a lot of activity.

The issue happens when multiple worflows try to push to the same gh-pages branch at the same time. This could happen, but there is no way around it.

[jorgepiloto]

I just took a look to the action that @germa89 shared. It is quite outdated. I thought about cloning it but no license so far. We will need to implement it on our side. It should not be a difficult task. The logic is similar to our dev and stable deployment actions.

[RobPasMue]

Agreed - we should just implement the mechanism to clean it up after merging - I think that might be the hardest part (making it robust).

[ludovicsteinbach]

It's on Github's roadmap as a feature https://github.com/orgs/community/discussions/7730#discussioncomment-7603270, but no delivery date yet