date:20181104

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
  n...@python.org -- []

___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Sorin Sbarnea

I can confirm that this is what OpenStack does. Sometimes the build artifacts 
(logs, docs ...) are rotated in two weeks but this is more than enough to 
perform a review. If I remember well retention is based on disk space and not 
hardcoded to a number of days, which is great.

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

I hope to see the same on python too, very useful.

> On 4 Nov 2018, at 23:48, Victor Stinner  wrote:
> 
> OpenStack does that on review.openstack.org  
> PRs. If I recall correctly, the CI produces files which are online on a 
> static web server. Nothing crazy. And it works. Old files are removed, I 
> don't know when exactly.
> 
> I don't think that it matters where the static files are hosted.
> 
> Victor
> 
> Le dimanche 4 novembre 2018, Stephane Wirtel  > a écrit :
> > 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-1-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/vstinner%40redhat.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/sorin.sbarnea%40gmail.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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Victor Stinner

OpenStack does that on review.openstack.org PRs. If I recall correctly, the
CI produces files which are online on a static web server. Nothing crazy.
And it works. Old files are removed, I don't know when exactly.

I don't think that it matters where the static files are hosted.

Victor

Le dimanche 4 novembre 2018, Stephane Wirtel  a écrit :
> 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-1-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/vstinner%40redhat.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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Paul Ganssle

On 11/4/18 5:38 PM, Steven D'Aprano wrote:
> 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".
>
I can only speak from my experience with setuptools, but I do look at
every setuptools PR and I've never seen anything even close to this.
That said, I have also never seen anyone using my Travis or Appveyor
instances to mine cryptocurrency, but I've been told that that happens.

In any case, I think the standard should not be "this never happens"
(otherwise you also can't run CI), but that it happens rarely enough
that it's not a major problem and that you can deal with it when it does
come up. Frankly, I think the much more likely target for these sorts of
attacks is small, mostly abandoned projects with very few followers. If
you post a spam site on some ephemeral domain via the CPython CI, it's
likely that hundreds of people will notice it just because it's a very
active project. You will be banned from the project for life and
probably reported to github nearly instantly. Likely you have much more
value for your time if you target some 1-star repo that set this up 2
years ago and is maintained by someone who hasn't committed to github in
over a year.

That said, big projects like CPython are probably more likely to attract
the troll version of this, where the point isn't to get away with
hosting some content or using the CI, but to annoy and disrupt the
project itself by wasting our resources chasing down spam or whatever. I
think if that isn't already happening with comment floods on the issue
tracker, GH threads and mailing lists, it's not especially /more/ likely
to happen because people can spin up a website with a PR.

>>> 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.

I think there are two concerns - one is that the python.org domain is
generally (currently) used for official content. If people can put
arbitrary websites on there, presumably they can exploit whatever trust
people have put into this fact.

Another is that - and I am not a web expert here - I think that the
domain where content is hosted is used as a marker of trust between
different pages, and many applications will consider anything on
*.python.org to be first-party content from other *.python.org domains. 
I believe this is the reason why readthedocs moved all hosted
documentation from *.readthedocs.org to *.readthedocs.io. Similarly
user-submitted content on PyPI is usually hosted under the
pythonhosted.org domain, not pypi.org or pypi.python.org. You'll notice
that GH also hosts user content under a githubusercontent.org domain.

signature.asc
Description: OpenPGP digital signature
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

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?


-- 
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Miro Hrončok

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

On 11/04, Serhiy Storchaka 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
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-variables-in-travisyml

--
Miro Hrončok
--
Phone: +420777974800
IRC: mhroncok
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


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
 n...@python.org -- []



--
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/04, Paul Ganssle wrote:

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).

Yep, I am fine with that.

Thanks Paul



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
  n...@python.org -- []









___
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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Paul Ganssle

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
>   n...@python.org -- []
>

signature.asc
Description: OpenPGP digital signature
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

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
  n...@python.org -- []

___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Paul Ganssle

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 > list=sdamon@python.org> 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-1-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

signature.asc
Description: OpenPGP digital signature
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

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 Deily
  n...@python.org -- []

___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Alex Walters

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  list=sdamon@python.org> 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-1-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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Steve Dower


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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Mariatta Wijaya

I think the intent is just uploading the output HTML and static assets.

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.

On Sun, Nov 4, 2018, 7:43 AM Serhiy Storchaka  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.
>
> ___
> 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/mariatta%40python.org
>
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Mariatta Wijaya

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.

On Sun, Nov 4, 2018, 7:56 AM Steven D'Aprano  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
> ___
> 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/mariatta%40python.org
>
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Julien Palard via Python-Dev

> 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?

-- 
Julien Palard
https://mdk.fr

___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/05, Steven D'Aprano wrote:

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
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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

On 11/05, Chris Angelico wrote:

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
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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Chris Angelico

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.

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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/04, Serhiy Storchaka 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
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


___
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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/04, Steve Dower wrote:

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
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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Serhiy Storchaka


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.


___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Steve Dower


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)


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.


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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


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
___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/04, Julien Palard 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.

+1

We have 2 options

1. We keep a domain (python.org, or another one) and for each build we would 
have a subdomain for
each build by PR.
doc-pr-XYZ.domain.tld

2. We could store on domain but with a subdirectory by PR
domain.tld/doc-pr-XYZ

In travis, I think we have the PR info, we could use it and upload to
the server for the live preview.

Once merged, we drop the temporary doc on the server.


Stéphane



-- 
Julien Palard
https://mdk.fr



--
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread Chris Angelico

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

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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.


On 11/04, Ned Deily wrote:

On Nov 4, 2018, at 08:38, Stephane Wirtel  wrote:

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-1-doc.python.org or whatever, but by this way the
reviewers could see the result online.


It's an interesting idea but I don't like essentially opening
python.org as a publishing platform (OK, another publishing platform -
yes, I know about wiki.python.org).  Considering how easy it is to
build and view the docs yourself, I don't think the benefits of such a
service are worth the added complexity and potential abuse.

cd Doc
make venv # first time
git pr checkout ...
make html
open build/html/index.html  # depending on platform and code change


I am going to give your 3 counter-examples but I think you will find an
other counter-example ;-)

1. Two weeks ago, I have opened a PR
[https://github.com/python/cpython/pull/10009] about a rewording of a
sentence in the doc. Paul Ganssle was a reviewer and in a sentence he
said that would be nice to have a live preview of the docs on PR.
See https://github.com/python/cpython/pull/10009#issuecomment-433082605
Maybe he was on his smartphone/tablet and not in front of his computer.

2. On this morning, I was reviewing a PR
https://github.com/python/cpython/pull/10102, but the message from the
reviewer was "LGTM. Thanks for the PR ;-)". I don't doubt about the
reviewer but I want to check the result of sphinx and not just the
text, sometimes, we can find an other issue, you never know.

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.


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)

We could check easily the result without this big step.

git wpr -> wpr = !bash -c \"git fetch upstream pull/${1}/head:pr_${1} && git 
worktree add ../$(basename $(git rev-parse --show-toplevel))-pr-${1} pr_${1}\" -

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

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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

2018-11-04 Thread 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.

-- 
Julien Palard
https://mdk.fr

___
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/archive%40mail-archive.com

Re: [Python-Dev] Get a running instance of the doc for a PR.

On Nov 4, 2018, at 08:38, Stephane Wirtel  wrote:
> 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-1-doc.python.org or whatever, but by this way the
> reviewers could see the result online.

It's an interesting idea but I don't like essentially opening python.org as a 
publishing platform (OK, another publishing platform - yes, I know about 
wiki.python.org).  Considering how easy it is to build and view the docs 
yourself, I don't think the benefits of such a service are worth the added 
complexity and potential abuse.

cd Doc
make venv # first time
git pr checkout ...
make html
open build/html/index.html  # depending on platform and code change

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

___
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/archive%40mail-archive.com

[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-1-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/archive%40mail-archive.com

Re: [Python-Dev] Need discussion for a PR about memory and objects

On Sun, Nov 04, 2018 at 11:43:50AM +0100, Stephane Wirtel wrote:
> In this PR [https://github.com/python/cpython/pull/3382] "Remove reference 
> to
> address from the docs, as it only causes confusion", opened by Chris
> Angelico, there is a discussion about the right term to use for the
> address of an object in memory.

Why do we need to refer to the address of objects in memory?

Python's execution model is not based on addresses. We can't get the 
address of an object or do anything with it (except via ctypes). At the 
Python layer, objects just exist, they don't logically exist at any 
addressable location.

In fact, they might not exist in a single location -- compound objects 
are split across many locations or can share chunks of memory between 
multiple objects. Objects in Jython and IronPython can move about, those 
in PyPy can disappear from existence and reappear. The concept that 
every object has exactly one fixed location simply isn't correct.

I understand that people wishing to understand the implementation 
details of CPython objects will need to think about C-level concepts 
like memory address, but at the Python level, "address" is not a very 
meaningful or useful concept.

-- 
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/archive%40mail-archive.com

[Python-Dev] Need discussion for a PR about memory and objects