On 11/04, Ned Deily wrote:
On Nov 4, 2018, at 08:38, Stephane Wirtel <steph...@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
_______________________________________________
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
