New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Doc files deleted from repo are not deleted from docs.python.org. #66155
Comments
There was an old document in the "howto" folder whose advice was in many cases flat-out wrong, so Raymond Hettinger performed a wonderful public service by deleting it back in 2011: http://hg.python.org/cpython/rev/80ff78425419 Unfortunately it looks like the process for publishing Python documentation only adds documents, but never deletes them, so a copy of the documentation is still available under the "3.4" document tree: https://docs.python.org/3.4/howto/doanddont.html It should be deleted as soon as possible. Because it is presumed that only the most accurate and up-to-date documentation lives under the URL "3.4", people are reading and debating this document's bad advice as though it is official guidance as to how to use the language. (The only hint that something is wrong, alas, is the tiny detail that the top-left of the page says “Python v3.3a0 documentation”). The advice is currently being debated on Twitter and people are sad that they are supposed to stop using “from foo import bar” in Python. |
What advice is "flat-out wrong"? All the advice seems excellent to me:
Why delete it rather than fix any (alleged) problems with it?
Debated on Twitter. Why am I not surprised that they've misunderstood it? The document explains why "from foo import bar" can *sometimes* be harmful. The wording could be improved, and isn't as clear as it should be, but the advice is broadly correct: "from foo import bar" injects the object bar into the current namespace, not the name, which means that if foo rebinds bar, that change will not be seen in the current namespace. If foo never rebinds bar, then there is no problem, but if bar is a *variable* rather than a (pseudo-)constant, you may run into subtle and tricky problems. -1 on deleting. If the consensus is to keep it, I'll look at rewording and improving some of the weaker descriptions. |
The question of whether the document ought to be removed is not at issue here. The document was already deleted, in 2011, by Raymond Hettinger, with the consent of its author. I told that story merely as background. The issue here is that the Python web site is out of date with the documentation in the Mercurial source repository, which is clear because what is clearly marked as an old 3.3-alpha document is being served out of the /3.4/ directory. This is probably because the documentation “push” script does not remove documents from the site, and can be corrected through a simple "rm" by anyone with access to the server. |
The file no longer exists in the 3.5 tree on the server. Since it isn't linked from the 3.4 index, it may be more effort than it is worth to get someone to delete the file from the 3.4 tree on the server. On the other hand, fixing the publication process to delete files is something the doc team should probably tackle (note: it might be a sphinx issue, but as Brandon says is more likely an issue with the script that publishes the pages to the server). As for revising the howto and re-adding it, that is a separate issue and should be discussed on the original bpo-7391, where the possibility was already raised and got some support. |
It would be worthwhile to delete or fix it in the 2.7 and 3.4 tree. It accidentally gets linked, still causing confusion to 2.7 and 3.4 users: |
The docs state 'from module import name1, name2. - This is a “don’t” which is much weaker than the previous “don’t”s but is still something you should not do if you don’t have good reasons to do that.' How does that translate into 'The Python docs say that "from module import name1, name2" is an anti-idiom' ? |
Mark, I and a number of others simply misinterpreted the text in that section. |
I do not find it unreasonable, on a page of Python idioms, the we would call an example that explicitly says "Don't" in its title an "anti-idiom." |
Now that I am back at a full keyboard, I see that my previous response Might I be allowed another try? If so, then: @breamoreboy, I think that In short, the document title does not match the document itself. The title of the document sets forth the terms "Idiom" and "Anti-idiom" Instead, the body uses the simpler phrases "Do", "do not", and "should So the answer to your "How does that translate" question is that what So when the document says: from module import name1, name2. - This is a "don’t"... the careful reader who has noticed and remembered the title will from module import name1, name2. - This is an anti-idiom... Which is almost exactly the text of Audrey's tweet. |
This is resolved since python/docsbuild-scripts#28. It could still happen in very specific conditions, but not for a long time, see: |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: