It looks like Sphinx snuck in a new deprecation warning in Sphinx 1.6.3 which this is triggering. If you can easily fix it by replacing any use of sphinx.util.compat.Directive with docutils.parsers.rst.Directive (I think) then please do, else pin Sphinx to 1.6.2 in the Travis configuration.

And I think the culprit might be

For the deprecation warning, I documented the issue in bpo-30939 and PR #2721 (for master), also needed in other branches.

LIke Brett, I didn't thoroughly review the changes but, in general, LGTM. One concern: as is, making this change will immediately break all doc builds of Doc/whatsnew/changelog.rst (for example, https://docs.python.org/dev/whatsnew/changelog.html). Are you planning to change Doc/Makefile to automatically do a 'blurb' run? I think we need to.

I tried to restart the Travis doc build but it is now getting a 3/333 unused rules warning for make suspicious which is suspicious because I don't get that when doing a clean make suspicious locally.

So... make suspicious is itself suspicious? GREAT SUCCESS

I experimented with having Doc/Makefile run blurb merge. That works fine, but it's a bit uncomfortable having the doc build process output a file in ../Misc. I propose to change the documentation so blurb merge outputs to build/NEWS and update the references (e.g. whatsnew/changelog.rst).

This does make the Doc build process dependent on blurb, which I hadn't anticipated. But that's a natural enough outcome of the process. And we can easily update the make venv target of the doc makefile to also install blurb. I don't think this is a big deal.

@brettcannon: It looks to me like Travis built against an old version. Did I hit some sort of workflow bug?

I changed Doc/Makefile and pushed. This was local revision dc85bd9, which AFAICT was auto-merged on GitHub to revision 8163ffa44849 . This kicked off Travis CI build 7463 ( https://travis-ci.org/python/cpython/builds/254150043 ).

The build didn't work because I had to fix .travis.yaml too. So I pushed a second change, which on my side is revision a8f8d57 . That kicked off Travis CI build 7464 ( https://travis-ci.org/python/cpython/builds/254151401 ). But Travis build 7464 was run against 8163ffa44849 ! Both Travis builds 7463 and 7464 were based on the same revision.

What's strange is that on Travis's "requests" dashboard: https://travis-ci.org/python/cpython/requests
it shows the latest checkin comment for build 7464. But both builds were clearly based on the same revision. It even shows you that in the requests dashboard.

What's going on?

I may try to fool Travis into running another build by uploading a no-op revision.

The docs job fails on Travis CI because this job only clones the last 50 commits:

git clone --depth=50 https://github.com/python/cpython.git python/cpython

whereas blurb looks for a specific commit:

run("git log -r 7f777ed95a19224294949e1b4ce56bbffcb1fe9f")

I don't think that we can change how Travis CI clones a Git repository, so we should change how blurb checks if if's running in a Git repository. Maybe it should catch subprocess.SubprocessError on:

git_dir = run("git rev-parse --git-dir").strip()

To check if it's running in Git or not?

Looks like @Haypo spotted why the revision check is failing. A bit annoying but understandable since Travis doesn't want to pay the CPU/network costs of downloading the entire CPython repo.

As for having the build process depend on blurb, that's just life and I have no issue with it since we already depend on sphinx. If it becomes a really serious problem we can talk about just putting blurb into the cpython repo to essentially vendor blurb in Python itself.

I suspect @larryhastings did a release on Sunday of blurb and simply forgot to bump the version number to 1.0.2 (i.e. drop the dev1 part). Once that's confirmed it wasn't on purpose Larry or me can quickly fix the version number and do a non-dev release.

Booyah! We now pass CI testing in a post-blurb world. @ned-deily, care to review again?

@ned-deily where are you suggesting to document the use of make venv? https://devguide.python.org/docquality/#helping-with-the-developer-s-guide ?

@brettcannon The primary documentation for Doc builds is Doc/README.rst. All of the make targets should be described there. Adding something to that section of the devguide would be good, too.

I created GH-2953 to document make venv to help keep this moving forward.