bpo-30487: automatically create a venv and install Sphinx when running make

[cjrh]

#1743 went horribly wrong, and there are now too many people automatically subscribed to that PR so I closed it. Now that I've fixed the feature branch, I've reopened the PR here. @zware

https://bugs.python.org/issue30487

[zware]

Fixing these comments should be enough to make Travis happy; I'll try to get another look at it after that :)

[zware]

This should be a dependency of this target (after the : on the line above); it's not a command on its own.

[zware]

This message should still go after the actual creation of the venv.

[zware]

This should also check whether $(SPHINXBUILD) --version > /dev/null 2>&1 works, and only build the venv if it doesn't.

[cjrh]

I fixed your other comments. The tests pass. This, about checking whether the command runs, is a bit more interesting. Since the venv Makefile action will only run if the venv dir is absent (is that right?), it means that $(SPHINXBUILD) could never work, until the venv is created. So to get into the body, we need the situation to be that the venv has just been created. Therefore, (in this situation), $(SPHINXBUILD) could never work. So why check for it? (fyi all my experience with makefiles has been on this issue; feel free to assume that know very little about how it works :).

The other, separate complication is that blurb now uses the same venv so we have to be careful to not mess up anything to do with that other tool. I've run make html several times. It looks ok right now, and the blurb action appears to work correctly.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[cjrh]

I'll try to makes the fixes as soon as I can. Hopefully next day or two.

[zware]

Let me know when you're ready for me to take another look (see @bedevere-bot's message above).

[cjrh]

@zware thx for checking in. You can look now. Note my comment that starts with "I fixed your other comments. The tests pass. ". I was perhaps unclear there, but I'm basically asking: since the venv block in the Makefile will only run if venv dir is missing, "$(VENVDIR)/bin/sphinx-build" can never succeed until the venv is built; so why check whether $(SPHINXBUILD) --version > /dev/null 2>&1 works?

Also, it was necessary to change the "$(VENVDIR)/bin/sphinx-build" mentioned in the previous paragraph to "PATH=$(VENVDIR)/bin:$$PATH sphinx-build", due to upstream changes. You will see this in the diff.

Next, management of blurb is now also tied to management of Sphinx, since they share a virtualenv. The permutations get complicated if the user can set their own blurb, but not sphinx, or vice versa, or both, or neither, etc. I think that is all overkill and we should make the simple case work well, but it's your feature, tell me how you want it to be :)

[zware]

Thanks for the patch!