CI: Trigger preview of the web/docs
State: closed

xref #50832

This call tells a simple service in our new server to preview the docs to download the artifact and uncompress it in a directory  with the number of the PR in: https://pandas.pydata.org/preview/

Ideally we want to get #50897 merged before this one (otherwise the website can't be navigated clicking at the links).

Still need to check if the artifact is ready when the service is called, I think it's only ready after the CI job is over. So I may need to return from the webservice asynchronously and introduce a delay.

Labels:
name: Docs
name: CI
description: Continuous Integration
name: Web
description: pandas website

Comments:
Seems like indeed, the artifact is not yet ready when triggering the preview from the workflow. Returning from the webservice asynchronously and delaying and retrying the github api call to get the artifacts seems to be the way forward.
Preview docs at: https://pandas.pydata.org/preview/50899/
This pull request is stale because it has been open for thirty days with no activity. Please [update](https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#updating-your-pull-request) and respond to this comment if you're still interested in working on this.
@pandas-dev/pandas-core this (the web/doc previewer) is now ready. After the feedback of the dev call where this was discussed, and trying many approaches (github makes this a bit tricky), the behavior that makes more sense to me is:

- Once the doc build finishes, the CI job makes a call to a webservice to generate the preview
- The webservice responds immediately, and asynchronously will wait until the artifact is ready, and will publish its content in our preview service
- I added an action, that when a comment with the text `/preview` is written, it answers with another comment with the url where the docs preview is available (you can see how it works here: https://github.com/datapythonista/pandas/pull/4)

This is now working. The web service needs a bit more work (it's using my personal token, better error logging in case github is broken would be nice, I didn't implement the purging of old previews yet, and it should better be installed as a systemd service), and I need to publish it somewhere too (not sure if in a repo in the pandas org, the pydata org, or my own user, let me know if you've got any preference).

But I think we can merge this, and get the preview working already.
I think this is really great!

A thought: Maybe discoverability for this service can be an issue for non-regular submitters/reviewers. Maybe to start with (after we're sure everything runs smoothly) always let the service make a comment in the PR showing the link to the generated preview?

Very good point @topper-123. What I had in mind is that this is going to be more useful for reviewers than the original authors (who probably rendered the web/docs locally). That being said, I think it'd be good to add this to the documentation eventually (I wouldn't just yet, as it'd be good to have a experimental period and see how this works). For the automated comment, I agree it could be useful, but at the same time is going to cause a lot of noise. For people who are watching all activity in our repo, this would cause a new email for each opened PR. Open to it, but not sure if it's worth. I guess with documentation, and seeing that people who knows about it uses the comment may be enough.

But I'm surely open to try it, and if it's really too noisy, we can shut it down anytime.
Yeah, I hadn't thought about the emails, that would be noisy I agree, good point. I think it's fine then to use a  `/preview` command. As you say we can always discuss later if people appear to have trouble with discoverability.