classification
Title: DOC: automatically create a venv and install Sphinx when running make
Type: Stage: patch review
Components: Documentation Versions: Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cjrh, docs@python, ned.deily, willingc, zach.ware
Priority: normal Keywords: patch

Created on 2017-05-26 16:49 by cjrh, last changed 2017-11-27 22:07 by ned.deily.

Pull Requests
URL Status Linked Edit
PR 1743 closed cjrh, 2017-05-26 16:49
PR 4346 merged cjrh, 2017-11-09 10:47
PR 4592 merged ned.deily, 2017-11-27 21:50
Messages (13)
msg294556 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-05-26 16:49
Under guidance from zware during Pycon sprints, I've changed the Doc/ Makefile to automatically create a virtual environment and install Sphinx, all as part of the `make html` command.
msg305932 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-11-09 03:58
I messed up the PR through a failed rebase (trying to rebase my PR on top of upstream). I closed the PR as a result.  I have now fixed up my feature branch, but I have not resubmitted the PR.  Since the PR was left alone for many months, I'm ok with leaving things as is, and close this issue?
msg305936 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2017-11-09 05:04
You should be able to force-push your branch (`git push -f origin auto-venv-docbuilder`, or replace `origin` with the correct remote name) to fix the existing PR.

Sorry I haven't gotten back to this previously; time to do a review and remembering that the PR exists have not coincided.
msg305955 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-11-09 10:50
No worries. I've made a new PR 4346. The old one was unsalvagable I'm afraid. Too many other people got added to the notifications list as a result of my incorrect rebase.  The new one is fine.
msg307019 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2017-11-26 21:18
New changeset d8d6b9122134f040cd5a4f15f40f6c9e3386db4d by Zachary Ware (Caleb Hattingh) in branch 'master':
bpo-30487: automatically create a venv and install Sphinx when running make (GH-4346)
https://github.com/python/cpython/commit/d8d6b9122134f040cd5a4f15f40f6c9e3386db4d
msg307082 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2017-11-27 21:12
I don't think this is a good idea. It has already caused problems with one buildbot (Issue32149) and will likely break other build scripts.  As the Doc Makefile stood previous to this commit, the Doc builds could take advantage of either a system-installed or user-supplied Sphinx and blurb without having to use the venv step.  Unless there are major objections, I am going to at least temporarily revert it.
msg307085 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-11-27 21:23
Hi Ned

It's still supposed to allow both. It sounds like it's not working properly. I'll have a look. FYI, I worked on this for Zach Ware who is the primary stakeholder for this feature. 

Rgds
Caleb

> On 28 Nov 2017, at 7:12 AM, Ned Deily <report@bugs.python.org> wrote:
> 
> 
> Ned Deily <nad@python.org> added the comment:
> 
> I don't think this is a good idea. It has already caused problems with one buildbot (Issue32149) and will likely break other build scripts.  As the Doc Makefile stood previous to this commit, the Doc builds could take advantage of either a system-installed or user-supplied Sphinx and blurb without having to use the venv step.  Unless there are major objections, I am going to at least temporarily revert it.
> 
> ----------
> nosy: +ned.deily
> resolution: fixed -> 
> stage: resolved -> needs patch
> status: closed -> open
> 
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue30487>
> _______________________________________
msg307086 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2017-11-27 21:26
One problem is that the venv can't always be automatically built in all environments, as a recent Python 3 needs to be available in the right location.
msg307087 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2017-11-27 21:40
Go ahead with the revert, Ned.
msg307090 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-11-27 21:58
It looks like the check for an existing sphinx-build passes, and so no new venv is made, but this also means that blurb doesn't get installed.  I was concerned about this, but figured that at least the buildbots would create new envs each time, and this would only be an issue that a user with an odd configuration might have.

Sorry for the trouble.

The feature was simpler when it was only sphinx.  Now that blurb is there too, the logic for checking what is and isn't already present becomes a bit complex to reason through.
msg307092 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2017-11-27 22:03
"Now that blurb is there too, the logic for checking what is and isn't already present becomes a bit complex to reason through."

Yeah, it is a bit complicated.  There's also the issue of trying to use a make recipe to ensure a "venv" exists and is up-to-date.  I don't necessarily want to abandon the idea (and sorry I wasn't around to review the proposed change initially) but let's at least hold off until 370a3 is out the door.
msg307094 - (view) Author: Caleb Hattingh (cjrh) * Date: 2017-11-27 22:04
Yep, sounds good.
msg307097 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2017-11-27 22:07
New changeset 122fc136b34e11906466851e77bb6959946467ee by Ned Deily in branch 'master':
Revert "bpo-30487: automatically create a venv and install Sphinx when running make (GH-4346)" (#4592)
https://github.com/python/cpython/commit/122fc136b34e11906466851e77bb6959946467ee
History
Date User Action Args
2017-11-27 22:07:34ned.deilysetmessages: + msg307097
2017-11-27 22:04:19cjrhsetmessages: + msg307094
2017-11-27 22:03:18ned.deilysetmessages: + msg307092
2017-11-27 21:58:15cjrhsetmessages: + msg307090
2017-11-27 21:50:18ned.deilysetstage: needs patch -> patch review
pull_requests: + pull_request4516
2017-11-27 21:40:29zach.waresetmessages: + msg307087
2017-11-27 21:26:50ned.deilysetmessages: + msg307086
2017-11-27 21:23:33cjrhsetmessages: + msg307085
2017-11-27 21:12:46ned.deilysetstatus: closed -> open

nosy: + ned.deily
messages: + msg307082

resolution: fixed ->
stage: resolved -> needs patch
2017-11-26 21:20:07zach.waresetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2017-11-26 21:18:32zach.waresetmessages: + msg307019
2017-11-09 10:50:19cjrhsetmessages: + msg305955
2017-11-09 10:47:33cjrhsetkeywords: + patch
pull_requests: + pull_request4303
2017-11-09 05:04:05zach.waresetmessages: + msg305936
2017-11-09 03:58:32cjrhsetmessages: + msg305932
2017-05-26 16:51:33Mariattasetstage: patch review
2017-05-26 16:49:48cjrhcreate