Preview documentation in a PR

Some of the Continuous Integration tools do a complete documentation rebuild for every PR so that they can report any markup errors or trailing spaces. It would be nice if we could see the docs they built.

This would be especially helpful for PRs that are adding a whole new section to the docs (e.g. the assignment expressions patch or the multiprocessing shared memory patch). Right now, we either have to look at the raw markup or pull down the PR and build the docs ourselves. As a reviewer, I like to see the docs in their final form to assess their intelligibility.

6 Likes

I remember @matrixise speaking about it, I like the idea too, dont’t know if someone tried implementing something.

IIRC the idea was the CI could push to a hosting machine/service (like a HTTP POST of the tarball), the response could provide the link to the temporarily hosted doc.

Relevant thread : https://mail.python.org/pipermail/python-dev/2018-November/155651.html

@julien i will continue this job, next week.

1 Like

More generally, using a service like https://mybinder.org/ one could actually try out the PR. It wouldn’t take that much effort to set up a “try this PR in binder” service. We’re considering setting up such a thing for SageMath.

We can use Netlify. We’ve started using netlify to preview DevGuide PRs. So it’s a matter of setting it up for CPython.

4 Likes

Although mybinder.org could be used to try out PRs for docs, it’s really not its primary purpose for general projects but more for reproducible science (@jdemeyer SageMath would be one such project).

Netlify has worked well for us on the nteract project and the DevGuide.

What I wanted to say is that it could be used for trying out PRs in general, not just for docs. You could have an actual Python console or Jupyter notebook running the code from the PR.

Hi @jdemeyer,

Yes, one could technically do what you are suggesting.

As a maintainer of mybinder.org, what I’m trying to clarify is that service’s mission is to provide a resource for reproducible science. We are not a revenue generating project and are funded through the generosity of a Moore Foundation grant. As such, I would like to discourage its use as a CI/testing service.

If someone were to wish to use it at scale to regularly to render and try out PRs, it would be better to set up their own BinderHub instance maintained on their compute resources.

Thanks for mentioning and supporting its usefulness. :smile: The team appreciates that folks find mybinder.org helpful.

1 Like

There’s the usual security issue of letting people (anybody can submit a PR) run arbitrary code in the execution environment.

1 Like

Binder runs everything in an isolated environment, so I don’t think that there is much of a security issue here.

I don’t forget to work on this issue. but I don’t have time for the moment :confused: