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

[Stephane Wirtel]

On 11/04, Ned Deily wrote:
>On Nov 4, 2018, at 08:38, Stephane Wirtel <stephane at wirtel.be> 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-10000-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