Codecov Report

Merging #45 into master will decrease coverage by -0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master      #45      +/-   ##
==========================================
- Coverage   82.37%   82.37%   -0.01%     
==========================================
  Files        1427     1427              
  Lines      350948   350948              
==========================================
- Hits       289089   289081       -8     
- Misses      61859    61867       +8

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2294f3a...62a9a46. Read the comment docs.

Commits a140a7f and 62a9a46 address those of @bitdancer 's comments with which I agree. There are still some paragraphs where we are not yet resolved. Please continue reviewing.

Sorry to say that overall I don't think this reads any better than what we have now and is in some ways worse. Instead of a rewrite effort, please focus on any one part that have reason to believe to be misleading. These docs have been around a long time and have worked reasonably well for a lot of users. Much of this I believe was written originally by Tim Peters who has knack for saying just what needs to be said.

@rhettinger Thank you for looking at this. I'm sorry to hear that it doesn't read any better for you.

This is not a rewrite effort. This is a targeted change to those sections where inadequate explanation misled me when I was writing my doctests. Specifically the existing docs aren't clear about when to use >>> and when to use ..., doesn't demonstrate how to use an imported module in a doctest, and doesn't talk clearly about the execution context within a docstring. My changes try to improve those points.

Perhaps you could point out the places where this version is worse? I could improve those.

Comments from others?

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.

Reviewers: Thank you very much for your attention to this PR and to bpo-29428. I have a feeling we are getting stuck. I have a feeling that part of the problem is that the Github review process doesn't work as well for diffuse issues in a document as it does for atomic issues in code. Part of the problem is that Github doesn't give us tools to have a conversation. Part of the problem is that reasonable people can disagree about writing style (I received contradictory feedback from reviewers).

If we were in a company, this would be the point where I would propose having a meeting. We could talk through the issues.

But this is the Python project. I don't know what the best way to make progress is. What should I do to make progress?

The fundamental problem I want to solve with this P.R. is: I wanted to write a doctest which required an import statement to get a module needed for an example. This documentation did not show me how to do that. I want to improve this documentation so that the next person who thinks they need to import a module for a doctest example will have better guidance.

A secondary goal is to improve the document overall. I see unclear writing and inconsistent terminology. I hear pushback against changes that are not "atomic". Overall document improvements won't be atomic. How does the Python project improve documents overall?

Also, In https://bugs.python.org/msg286973 Marco Bhutto proposed adding a Howto for doctests. A Howto might be a way to make progress on my goals, but I fear that a newbie like me will not be able to write a Howto that will survive the sort of review this PR has received.

Reviewers: Thank you very much for your attention to this PR

Thank you for contributing, I see this thread is way too long for your original goal.

The fundamental problem I want to solve with this P.R. is: I wanted to write a doctest which required an import statement to get a module needed for an example. This documentation did not show me how to do that.

The documentation (https://docs.python.org/3.6/library/doctest.html#simple-usage-checking-examples-in-a-text-file) give this exact example of separating the import and example:

This is an example text file in reStructuredText format.  First import
``factorial`` from the ``example`` module:

    >>> from example import factorial

Now use it:

    >>> factorial(6)
    120

A secondary goal is to improve the document overall.

This is probably why your PR is stuck, it make your PR too big for the original issue. Try to fix your issue first, as simply as possible, and then, in another PR, try to improve the document overall.

I see unclear writing and inconsistent terminology.

An issue and a PR about them would be appreciated, let's not pollute this already bloath thread with out-of-topic issues.

I hear pushback against changes that are not "atomic".

Yes, atomic chances are faster to review and faster to merge. As you said you're trying to fix an issue AND improving the overall document, this is a "comment magnet" as you see.

Overall document improvements won't be atomic.

Overall improvements can also be specifics: First fix the inconsistency on a single word. Then another word. Then a paragraph. Then add an example. Then ...

How does the Python project improve documents overall?

Run "git log -p Doc/" in your cpython clone, yes it goes slowly, (yes there's not much people really interested in participating full-time on the documentation).

Also, In https://bugs.python.org/msg286973 Marco Bhutto proposed adding a Howto for doctests. A Howto might be a way to make progress on my goals, but I fear that a newbie like me will not be able to write a Howto that will survive the sort of review this PR has received.

In one hand it looks like a big chunk to do. In the other, being a newcomer can help you to know what should be explained to newcomers, so it may end up interesting for other newcomers. Anyway please open a separate issue / PR to discuss this.

What should I do to make progress?

First, don't get bit by https://en.wikipedia.org/wiki/Sunk_cost this is not because we all (especially you) spent a lot of time on this PR that it have to still grow.

I'll in contrast simplify the PR a lot. Look the paragraph [https://docs.python.org/3.6/library/doctest.html#what-s-the-execution-context](26.3.3.3. What’s the Execution Context?), it's really short, and it is the one explainig the scope (This is the one containing the sentence "and names defined earlier in the docstring being run", directly in relation with your issue) maybe you can add your example in it (the one with import math). But refrain from also demoing the ";" in it, it's another example, showing something else, don't mix them, it just make them hard to read. There's probably other places where

But this is the Python project. I don't know what the best way to make progress is. What should I do to make progress?

Thanks @JDLH for taking the time to create a PR, and thanks to @bitdancer, @JulienPalard, and @rhettinger for the effort to review.

I'm recommending that this PR be closed as it is languishing due to its scope being too broad. If you wish to break this PR up into a smaller PR with one atomic change, I will be happy to review the new PR. Thanks.