bpo-27200: fix unittest.mock doctests.

[marco-buttu]

This PR is the last one in the series bpo-27200. The other PRs were: #240, #401, #604, and #616. After applying all PRs in the series, all doctests will pass. At this point we can add the doctest check in the build.

To run the doctests (from the Doc directory):

$ sphinx-build -b doctest . build/doctest library/unittest.mock*

[mention-bot]

@marco-buttu, thanks for your PR! By analyzing the history of the files in this pull request, we identified @mfoord, @birkenfeld and @tiran to be potential reviewers.

[berkerpeksag]

IMO, this is too much work for a little gain. I prefer to skip unittest.mock altogether instead of adding too much code just to make tests runnable by doctest.

[marco-buttu]

Ok @berkerpeksag, I skip all tests that do not pass, just adding some missed imports

[berkerpeksag]

I skip all tests that do not pass, just adding some missed imports

That sounds better, thanks! Did you push your changes or should I wait for a bit?

[marco-buttu]

I think I will need a couple of hours to finish the job. I will tag you when it is ready. Thanks :-)

[marco-buttu]

@berkerpeksag, it is done but we have a problem :( Skipping the tests that do not pass, we touch a lot of lines, more than in the previous version:

• Spikking tests (485 tests executed, 0 failures): 2 files changed,+642 -464;
• Executing tests (666 tests executed, 0 failures): 8 files changed, +213, -25.

That is because a lot of examples are chained, and when we skip one of them, we need to skip all next examples that use the names defined in the skipped test. And bacause we are skipping the examples using the doctest directive, instead of :: (as discussed in #604), we need to deindent them to align the code to the doctest. That is why we are touching a lot of lines. What if we apply the "Although practicality beats purity" aphorism of the Zen, and for this PR we use the :: instead of the doctest directive? The review will be much easier

[marco-buttu]

@berkerpeksag I aligned :options: to the code examples indentation -- it is allowed by the
reST spec --

[zware]

@berkerpeksag Do you have time to give this another review?

[berkerpeksag]

Thank you for working on this, @marco-buttu. Sorry, I missed this one earlier. I agree that the last version creates too much noise in the diff. Reading the conversation again, I wonder if we should skip converting Doc/library/unittest.mock* files for now.

If I recall correctly, there was some discussions to reorganize mock docs and make them more compatible with our general documentation guidelines (because we basically copy & pasted them without making too much changes when we initially added mock to stdlib) so I'm beginning to think that the doctest conversion should be next step after the reorganization is done.

How do you plan to integrate doctests into Travis CI? Is it hard to skip Doc/library/unittest.mock* files?

[marco-buttu]

@berkerpeksag as you prefere. If you want us to first work on the new version before fixing the doctests, it is also fine to me. About how to integrate doctests into Travis CI, I am not an expert of Travis CI... I just thought it was as easy as adding the make doctest to the script on .travis.yml . If you want us to skip only the Doc/library/unittest.mock* files, I do not know any proper way to do it :/ Currently I only have this solution:

$ find . -type f -name '*.rst' -not -name '*unittest.mock*' -print0 | 
xargs -0 sphinx-build  -b doctest . build/doctest
...
Doctest summary
===============
 1413 tests
    0 failures in tests
    0 failures in setup code
    0 failures in cleanup code
build succeeded.

[brettcannon]

To try and help move older pull requests forward, we are going through and backfilling 'awaiting' labels on pull requests that are lacking the label. Based on the current reviews, the best we can tell in an automated fashion is that a core developer requested changes to be made to this pull request.

If/when the requested changes have been made, please leave a comment that says, I have made the requested changes; please review again. That will trigger a bot to flag this pull request as ready for a follow-up review.

[JulienPalard]

Hi @marco-buttu, @matrixise authored 859c068 which also fixes unittest.mock.rst, so I'm closing this PR.

@matrixise also enforced the doctests in travis-ci so you'll be happy: it whould never break again :)

BTW thanks for all previous PR initiating this long work 🍰