Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC. --  Julien Palard https://mdk.fr

On 11/05, Chris Angelico wrote:

On Mon, Nov 5, 2018 at 2:11 AM Julien Palard via Python-Dev wrote:

...

Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC.

After running 'make html', the build directory is the entire site as a set of static files, right? Maybe the easiest solution is to tie in with GitHub Pages. I already have a script that will push a directory up as the gh-pages branch of the current repo; it'd just need a tweak so it can push to a specific repo, which you could create on GitHub for the purpose. Not 100% automatic, but also not too difficult to automate, if needed.

https://github.com/Rosuav/shed/blob/master/git-deploy

Nice idea, but I am not for that. 1. We will populate the git repository with a lot of gh-pages branches and I am not for this solution 2. This static doc is just temporary, once merged, we have to remove the link and the content on the server, with the gh-pages, that will be a commit where we drop the content, but it's a commit and we will consume the storage of github. 3. 1 repo has only one gh-pages, in our case, we need to have a lot of gh-pages for a repo. But thank you for your idea. -- Stéphane Wirtel - https://wirtel.be - @matrixise

On Mon, Nov 5, 2018 at 2:33 AM Stephane Wirtel wrote:

...

On 11/05, Chris Angelico wrote:

...

On Mon, Nov 5, 2018 at 2:11 AM Julien Palard via Python-Dev wrote:

...

Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC.

After running 'make html', the build directory is the entire site as a set of static files, right? Maybe the easiest solution is to tie in with GitHub Pages. I already have a script that will push a directory up as the gh-pages branch of the current repo; it'd just need a tweak so it can push to a specific repo, which you could create on GitHub for the purpose. Not 100% automatic, but also not too difficult to automate, if needed.

https://github.com/Rosuav/shed/blob/master/git-deploy

Nice idea, but I am not for that.

1. We will populate the git repository with a lot of gh-pages branches and I am not for this solution 2. This static doc is just temporary, once merged, we have to remove the link and the content on the server, with the gh-pages, that will be a commit where we drop the content, but it's a commit and we will consume the storage of github. 3. 1 repo has only one gh-pages, in our case, we need to have a lot of gh-pages for a repo.

Yeah, understood. I was thinking of having the individual patch authors create temporary GitHub repositories to push to. It'd be an optional step; if you want to show people a preview of your PR, just create a repository and push to it (using a script something like that). That way, you don't have to worry about malicious content (since it'll be hosted under the author's name - I'm sure GitHub have measures in place to deal with that, and it wouldn't be Python.org's problem), nor having lots of gh-pages branches sitting around (they'd be the responsibility of the author).

...

But thank you for your idea.

No probs, and I don't mind if it's not adopted. Just wanted to put it out there. In fact, I was interested by your solution because we avoid the

On 11/05, Chris Angelico wrote: maintenance of the server, but in our case, we would host many Docs/build/html. Thanks again

ChrisA _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/stephane%40wirtel.be

-- Stéphane Wirtel - https://wirtel.be - @matrixise

On 04Nov2018 0718, Chris Angelico wrote:

...

On Mon, Nov 5, 2018 at 2:11 AM Julien Palard via Python-Dev wrote:

...

Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC.

After running 'make html', the build directory is the entire site as a set of static files, right? Maybe the easiest solution is to tie in with GitHub Pages. I already have a script that will push a directory up as the gh-pages branch of the current repo; it'd just need a tweak so it can push to a specific repo, which you could create on GitHub for the purpose. Not 100% automatic, but also not too difficult to automate, if needed.

I can trivially attach the built docs as a ZIP file to the Azure Pipelines build, though that doesn't help the "preview on my phone" scenario (unless your phone can extract and then open a directory of HTML files? Mine can't) Or just upload the zip file to the server-live-preview-doc and unzip the result.

But that's also easy enough to tie into a second step to deploy the files practically anywhere. Pushing them to a git repo based on the PR name is easy, and presumably it can be a single repo with directories for different PRs? It might need a separate job to periodically clean it up, but this seems very doable. for the subdirectory by PR I am not sure but we could have an issue with

On 11/04, Steve Dower wrote: the cache of the browser because we will use the same domain, but this solution can be created in few hours. +1 For the subdomain, no problem with the cache, just update the DNS, but we can have an issue with the propagation of the DNS if the TTL is high. We could use Bedevere, not sure but I think it can receive an action about the merge of a PR. Once merge, we execute the clean process ;-)

Cheers, Steve _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/stephane%40wirtel.be

-- Stéphane Wirtel - https://wirtel.be - @matrixise

On 04Nov2018 0812, Julien Palard wrote:

...

I can trivially attach the built docs as a ZIP file to the Azure Pipelines build, though that doesn't help the "preview on my phone"

So one can build an HTTP server that gathers doc builds from Azure and expose them?

Either that, or Azure can push it directly to the server. (This way is simpler, since the processing power is already there and the trigger is trivial, compared to triggering yet another service from the build completion. Though it does mean putting credentials somewhere, which is why a github repo is the easiest option, as those are already there.) Cheers, Steve

04.11.18 17:00, Julien Palard via Python-Dev пише:

Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC.

This will just move risks to this service. Ned mentioned potential abuse. We will host unchecked content. Malicious user can create a PR which replaces Python documentation with malicious content. The Doc/ directory includes Python scripts and Makefile which are used for building documentation. Malicious user can use this for executing arbitrary code on our server.

On 04. 11. 18 16:49, Stephane Wirtel wrote:

...

04.11.18 17:00, Julien Palard via Python-Dev пише:

...

Considering feedback from Ned, what about building this as an independent service? We don't really need to interface with python.org at all, we just need some hardware, a domain, some code to interface with github API and... to start it's probably enough? It would be a usefull POC.

This will just move risks to this service.

Ned mentioned potential abuse. We will host unchecked content. Malicious user can create a PR which replaces Python documentation with malicious content. The content will be generated by the build/html directory from Travis. If Travis is green we upload the doc, if Travis is red, we do not

On 11/04, Serhiy Storchaka wrote: publish it. If there is an abuse, we close/drop the PR, maybe Bedevere can receive this notification via the webhooks and notify the server to remove the doc.

...

The Doc/ directory includes Python scripts and Makefile which are used for building documentation. Malicious user can use this for executing arbitrary code on our server.

Currently, we use Travis. The malicious code will be execute in the container of Travis, not on the server. We only copy the static files and if we use nginx/apache, we don't execute the .py files. Just serve the .html,.css,.js files

Yet you need to let Travis CI know how to upload the results (HTML files) somewhere. That usually involves some kind of credentials. You can secretly tell Travis the credentials, however somebody would be able to modify the Makefile (or anything else) to send the credentials to their webservice/e-mail/whatever. That is in fact not possible, for exactly this reason: Travis CI builds from PRs don't see the "secret" stuff. https://docs.travis-ci.com/user/environment-variables#defining-encrypted-var... -- Miro Hrončok -- Phone: +420777974800 IRC: mhroncok

On 11/04, Mariatta Wijaya wrote:

I think the intent is just uploading the output HTML and static assets. Yep, it's my idea, just upload the output html and static assets, nothing else.

I agree having the temporary output of PR docs build is useful, but I don't think a python.org domain is necessary. If it can be uploaded to any cloud storage service then that's good enough, just provide the link in the status check. The output can be cleared after it receive the PR closed webhook. +1

And I think Bedevere is the best candidate for this feature (once closed, remove from the server) -- Stéphane Wirtel - https://wirtel.be - @matrixise

On Sun, Nov 04, 2018 at 04:12:39PM +0100, Stephane Wirtel wrote:

My workflow is the following steps:

git wpr XYZ cd ../cpython-XYZ ./configure --prefix=$PWD-build --with-pydebug --silent make -j 4 -s make PYTHON=../python -C Doc/ venv make -C Doc/ check suspicious html serve

and run the browser on http://localhost:8000/ and check the result.

1. Because I am a dev I can do it easily 2. If you are not a dev, you have to learn a new step (download sources, compile sources, compile doc and check the result)

If I am making doc patches, shouldn't I be doing that *before* I submit the PR? How else will I know that my changes haven't broken the docs? So surely I need to learn those steps regardless? (Not a rhetorical question.)

I think this feature would be really useful for the contributors, the reviewers and you, the core-dev.

Sure. But the usefulness has to be weighed against the extra complexity, the extra "one more thing that can break and needs to be maintained", and the risk of abuse. I have no opinion on whether the pluses outweigh the minuses. -- Steve

On 11/04, Mariatta Wijaya wrote:

This will make review turnout quicker, since I can potentially review and view the output from anywhere (phone while on a beach) instead of waiting until I'm back home, open a computer, and then verify the output myself. Yep, last week I was at a dinner at PyCon.DE, I have seen a PR, I wanted to check the result and approve it or not. With this feature, I can check it asap and just approve via github. Once approved, miss-islington could merge the PR, once merged, Bedevere can notify the service and remove the documentation of this PR.

-- Stéphane Wirtel - https://wirtel.be - @matrixise

On Sun, Nov 04, 2018 at 04:12:39PM +0100, Stephane Wirtel wrote:

...

My workflow is the following steps:

git wpr XYZ cd ../cpython-XYZ ./configure --prefix=$PWD-build --with-pydebug --silent make -j 4 -s make PYTHON=../python -C Doc/ venv make -C Doc/ check suspicious html serve

and run the browser on http://localhost:8000/ and check the result.

1. Because I am a dev I can do it easily 2. If you are not a dev, you have to learn a new step (download sources, compile sources, compile doc and check the result)

If I am making doc patches, shouldn't I be doing that *before* I submit the PR? How else will I know that my changes haven't broken the docs? You can use the web interface of Github and just add/remove/modify a

On 11/05, Steven D'Aprano wrote: paragraph.

So surely I need to learn those steps regardless?

(Not a rhetorical question.)

...

I think this feature would be really useful for the contributors, the reviewers and you, the core-dev.

Sure. But the usefulness has to be weighed against the extra complexity, the extra "one more thing that can break and needs to be maintained", and the risk of abuse.

Which kind of abuse? -- Stéphane Wirtel - https://wirtel.be - @matrixise

On Sun, 4 Nov 2018 at 14:49, Steven D'Aprano wrote:

On Sun, Nov 04, 2018 at 05:05:07PM +0100, Stephane Wirtel wrote:

...

...

If I am making doc patches, shouldn't I be doing that *before* I submit the PR? How else will I know that my changes haven't broken the docs?

You can use the web interface of Github and just add/remove/modify a paragraph.

Does Github show a preview? If not, then my question still stands: how do I know my changes aren't broken?

If Github does show a preview, then couldn't the reviewer look at that too?

GitHub provides a "View" button for files while viewing a diff which will do a basic render for reST files. It won't change all the references like sealso and such, but basic stuff like literals and links will show up appropriately. I think baby steps are probably best here, so getting a zip file as Steve pointed out to start is still an improvement than the status quo and much easier to implement. And any further discussion should probably happen over on core-workflow.

On 11/04, Ned Deily wrote:

On Nov 4, 2018, at 10:12, Stephane Wirtel wrote:

...

3. On this after-noon, I have reviewed a PR, and I was in the same case, download the PR, build python, compile the doc and run the local server.

My workflow is the following steps:

git wpr XYZ cd ../cpython-XYZ ./configure --prefix=$PWD-build --with-pydebug --silent make -j 4 -s make PYTHON=../python -C Doc/ venv make -C Doc/ check suspicious html serve

and run the browser on http://localhost:8000/ and check the result.

To address one point, there's no need to run a web server to review the docs. The generated docs can be viewed directly by any modern web browser by opening one of the files in the web browser's file menu. Or perhaps easier, you can click on any of the generated html files; or on macOS you can use the open(1) command from the shell to open and view in the default web browser.

$ open build/html/index.html Ned, I agree with you about this point, but there is an advantage when you use localhost:8000, you only have one entrypoint. And when you switch between many PR, you just have to execute the make -C Doc/ serve command (because in my workflow and with the full URI, the path can change in function of the PR, I use git worktree for each PR).

But yep, I am +1 for firefox build/html/index.html

-- Ned Deily nad@python.org -- []

-- Stéphane Wirtel - https://wirtel.be - @matrixise

There is an open request for this on GH, but it's not currently done: https://github.com/rtfd/readthedocs.org/issues/1340 At the PyCon US sprints this year, we added documentation previews via netlify, and they have been super useful: https://github.com/pypa/setuptools/pull/1367 My understanding is that other projects do something similar with CircleCI. It's not amazingly /difficult/ for reviewers to fetch the submitter's branch, build the documentation and review it locally, but it's a decent number of extra steps for what /should/ be a very simple review. I think we all know that reviewer time and effort is one of the biggest bottlenecks in the CPython development workflow, and this could make it /much/ easier to do reviews. Some of the concerns about increasing the surface area I think are a bit overblown. I haven't seen any problems yet in the projects that do this, and I don't think it lends itself to abuse particularly well.//Considering that the rest of the CI suite lets you run arbitrary code on many platforms, I don't think it's particularly more dangerous to allow people to generate ephemeral static hosted web sites as well. Best. Paul On 11/4/18 11:28 AM, Alex Walters wrote:

Doesn't read the docs already do this for pull requests? Even if it doesn't, don't the core maintainers of read the docs go to pycon? I wouldn't suggest read the docs for primary docs hosting for python, but they are perfectly fine for live testing pull request documentation without having to roll our own.

...

-----Original Message----- From: Python-Dev On Behalf Of Stephane Wirtel Sent: Sunday, November 4, 2018 8:38 AM To: python-dev@python.org Subject: [Python-Dev] Get a running instance of the doc for a PR.

Hi all,

When we receive a PR about the documentation, I think that could be interesting if we could have a running instance of the doc on a sub domain of python.org.

For example, pr-10000-doc.python.org or whatever, but by this way the reviewers could see the result online.

The workflow would be like that:

New PR -> build the doc (done by Travis) -> publish it to a server -> once published, the PR is notified by "doc is available at URL".

Once merged -> we remove the doc and the link (hello bedevere).

I am interested by this feature and if you also interested, tell me. I would like discuss with Julien Palard and Ernest W. Durbin III for a solution as soon as possible.

Have a nice day,

Stéphane

-- Stéphane Wirtel - https://wirtel.be - @matrixise _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/tritium- list%40sdamon.com

---

Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/paul%40ganssle.io

Oh, sorry if I misunderstood the concern. Yes, I agree that putting this under python.org would not be a good idea. Either hosting it on a hosting provider like netlify (or azure if that's possible) or a dedicated domain that could be created for the purpose (e.g. python-doc-ci.org) would be best. Alternatively, the domain could be skipped entirely and the github hooks could link directly to documentation by machine IP (though I suspect buying a domain for this purpose would be a lot easier than coordinating what's necessary to make direct links to a machine IP reasonable). Best, Paul On 11/4/18 12:16 PM, Ned Deily wrote:

On Nov 4, 2018, at 12:04, Paul Ganssle wrote:

...

Some of the concerns about increasing the surface area I think are a bit overblown. I haven't seen any problems yet in the projects that do this, and I don't think it lends itself to abuse particularly well. Considering that the rest of the CI suite lets you run arbitrary code on many platforms, I don't think it's particularly more dangerous to allow people to generate ephemeral static hosted web sites as well. The rest of the CI suite does not let you publish things on the python.org domain, unless I'm forgetting something; they're clearly under a CI environment like Travis or AppVeyor or Azure. That's really my main concern.

-- Ned Deily nad@python.org -- []

On Sun, Nov 04, 2018 at 12:16:14PM -0500, Ned Deily wrote:

On Nov 4, 2018, at 12:04, Paul Ganssle wrote:

...

Some of the concerns about increasing the surface area I think are a bit overblown. I haven't seen any problems yet in the projects that do this,

You may or may not be right, but have you looked for problems or just assumed that because nobody has brought any to your attention, they don't exist? "I have seen nothing" != "there is nothing to see".

...

and I don't think it lends itself to abuse particularly well. Considering that the rest of the CI suite lets you run arbitrary code on many platforms, I don't think it's particularly more dangerous to allow people to generate ephemeral static hosted web sites as well.

The rest of the CI suite does not let you publish things on the python.org domain, unless I'm forgetting something; they're clearly under a CI environment like Travis or AppVeyor or Azure. That's really my main concern.

Sorry Ned, I don't follow you here. It sounds like you're saying that you're fine with spam or abusive content being hosted in our name, so long as its hosted by somebody else, rather than by us (python.org) ourselves. I trust I'm missing something, but I don't know what it is. -- Steve

Not to belabor the point but: On Nov 4, 2018, at 19:39, Sorin Sbarnea wrote:

TBH, I don't really know how a human can check the docs if they cannot access them on a webserver.

It's actually trivially easy with the Python doc set because the docs were designed to also be downloadable and usable off-line. That is, the same files html, js, css, and other resources that get built and loaded onto the website can also be just browsed directly from a file system, like: firefox Doc/build/html/index.html or, say, using the Open File command in Safari or whatever. No web server is needed. The docsets for the heads of each of the active branches are built and packaged nightly and downloadable from python.org: https://docs.python.org/3/download.html Also, archive copies of the docset at the time of each release is downloadable from here: https://www.python.org/doc/versions/ There are built using the same Doc/Makefile found in the cpython repo branches and the resulting Doc/build/html directory contains the docset for that snapshot of the repo with every file in the proper location for the webbrowser to load directly. -- Ned Deily nad@python.org -- []