[issue37860] Add netlify deploy preview for docs
New submission from Ashwin Ramaswami aramaswamis@gmail.com:
It would be good to preview the cpython documentation on PRs using Netlify.
See https://github.com/python/core-workflow/issues/348
---------- assignee: docs@python components: Documentation messages: 349752 nosy: docs@python, epicfaace priority: normal severity: normal status: open title: Add netlify deploy preview for docs versions: Python 3.9
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ashwin Ramaswami aramaswamis@gmail.com:
---------- nosy: +Mariatta
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ashwin Ramaswami aramaswamis@gmail.com:
---------- keywords: +patch pull_requests: +15012 stage: -> patch review pull_request: https://github.com/python/cpython/pull/15288
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Brett Cannon brett@python.org:
---------- nosy: +brett.cannon
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Carol Willing willingc@gmail.com added the comment:
New changeset 87bc3b7a0b0c41ea5da2aa137c4145f437a1c9fd by Carol Willing (Ashwin Ramaswami) in branch 'master': bpo-37860: Add netlify deploy preview for docs (GH-15288) https://github.com/python/cpython/commit/87bc3b7a0b0c41ea5da2aa137c4145f437a...
---------- nosy: +willingc
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ernest W. Durbin III ernest@python.org:
---------- pull_requests: +17622 pull_request: https://github.com/python/cpython/pull/18242
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ashwin Ramaswami aramaswamis@gmail.com:
---------- pull_requests: +18373 pull_request: https://github.com/python/cpython/pull/19025
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Ashwin Ramaswami aramaswamis@gmail.com added the comment:
Given Ernest's comment in https://github.com/python/cpython/pull/15288#issuecomment-579476340 about the limitations of Netlify (1000 build minutes per month), it doesn't seem like Netlify will be a viable alternative.
Instead, I've added a PR (https://github.com/python/cpython/pull/19025) that takes an alternative approach. It uses GitHub Actions to deploy the docs to the gh-pages branch, then adds a comment to the PR with a link to the deploy preview.
The way this works is that the gh-pages branch has subfolders with the SHA of each commit, and each deploy preview is deployed to each subfolder.
I've enabled this on my fork of cpython -- here's an example PR on my fork: https://github.com/epicfaace/cpython/pull/7
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Ashwin Ramaswami aramaswamis@gmail.com added the comment:
GitHub Pages has no limit on "build limits" like Netlify does.
One limitation of this approach, though, is that GitHub Pages sites are limited to 1 GB in size. Each doc build is 50 MB, meaning that we could host at a maximum 20 builds. If we needed to, we could resolve this by doing one (or multiple) of the following: - check with GitHub to see if they will increase the limit for this case - only build PRs that have been tagged "documentation" - add a workflow to automatically remove deploy previews after a certain amount of time has passed or after a PR has been merged - don't deploy on GitHub Pages, but use something like https://surge.sh/, which apparently doesn't have a hard limit on size of a static site
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Kyle Stanley aeros167@gmail.com added the comment:
only build PRs that have been tagged "documentation"
My preference would be to have a "preview-with-netlify" label that could be manually added to use the netlify preview on a case-by-case basis. There are a substantial number of trivial PRs (such as typo fixes and similar minor changes) that are automatically labelled as "documentation" which wouldn't particularly benefit from the netlify preview and would needlessly occupy part of the limit.
Personally, I feel that it most largely benefits more significant documentation changes that involve modification of existing markup or the addition of new markup, rather than all documentation PRs. So a manually added label to trigger it makes the most sense to me. This would be very similar to the recently added "test-with-buildbots" label.
---------- nosy: +aeros
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ashwin Ramaswami aramaswamis@gmail.com:
---------- title: Add netlify deploy preview for docs -> Add deploy preview for docs
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Batuhan Taskaya batuhanosmantaskaya@gmail.com:
---------- nosy: +BTaskaya
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Brett Cannon brett@python.org:
---------- nosy: -brett.cannon
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Batuhan Taskaya batuhanosmantaskaya@gmail.com added the comment:
Personally, I feel that it most largely benefits more significant documentation changes that involve modification of existing markup or the addition of new markup, rather than all documentation PRs. So a manually added label to trigger it makes the most sense to me. This would be very similar to the recently added "test-with-buildbots" label.
+1, It would be so much useful in cases like GH 19928.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Ashwin Ramaswami aramaswamis@gmail.com added the comment:
I realized there's another alternative which is probably simpler. We can use Netlify to host the deploy previews, but we can use GitHub Actions to build the documentation. This way, we won't run into the build time limits for Netlify, and we can still use Netlify to host deploy previews.
We can use this GitHub Actions action: https://github.com/marketplace/actions/netlify-actions, and just add it as an additional step to our existing doc GitHub Actions workflow (https://github.com/python/cpython/blob/master/.github/workflows/doc.yml).
What do you think about this approach?
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
Change by Ashwin Ramaswami aramaswamis@gmail.com:
---------- nosy: +EWDurbin
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue37860 _______________________________________
participants (6)
-
Ashwin Ramaswami -
Batuhan Taskaya
-
Brett Cannon
-
Carol Willing
-
Ernest W. Durbin III
-
Kyle Stanley