[issue22952] multiprocessing doc introduction not in affirmative tone
New submission from Davin Potts: The introduction section of the multiprocessing module's documentation does not adhere to the python dev guidelines for keeping things in the affirmative tone. Problem description: Specifically, the intro section contains a warning block that, while conveying something important, both 1) potentially creates worry/concern in the mind of the reader new to this module, and 2) ideally belongs somewhere more relevant/appropriate than the intro section. Also, the intro section contains an example code block that does not attempt to provide a simple example to advance understanding and boost the reader's confidence through trying this example -- instead it demonstrates what not to do and the consequences of doing so in an attempt to drive home one key point with the reader. Suggested changes: * The warning text block can be moved to a section discussing synchronization without losing the important information being shared or sharing it too late to be useful. * To make the key point to the reader in the intro about the availability/importability of functions, etc. to child processes, the affirmative tone can be used in describing the good pattern/practice being employed in a usable/valid/working example. Further comment: Similar issues could be raised with other parts of the multiprocessing docs but this issue is concerned only with the intro section. ---------- assignee: docs@python components: Documentation messages: 231731 nosy: davin, docs@python priority: normal severity: normal status: open title: multiprocessing doc introduction not in affirmative tone type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Davin Potts added the comment: Attached is a proposed patch for the 2.7 branch. It provides 2 changes to the documentation: 1) Moves the warning text block regarding synchronization functionality not necessarily being available on all systems to the "Synchronization between processes" section (Section 16.6.1.3 in the 2.7 docs). 2) Adds a paragraph introducing (in the affirmative tone) a good/common practice as shown in a working example to drive home the key point about importability by subprocesses. The original example of what not to do has been preserved by moving it to the "Using a pool of workers" section (Section 16.6.1.5 in the 2.7 docs). Note that this patch does not attempt to resolve the issue of :class:`Pool` not being resolved by Sphinx to properly point at the multiprocessing.pool.Pool class description. This issue appears addressed in the 3.4 docs but not in some other branches. ---------- keywords: +patch Added file: http://bugs.python.org/file37290/multiprocessing_27.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Davin Potts added the comment: Attached is a proposed patch for the 3.4 branch. The same modifications are made in this patch as in the patch for the 2.7 branch, with two minor tweaks: 1) The affirmative tone example uses Pool in a with statement as is supported since 3.3. 2) References in the added/moved text are properly resolving (in Sphinx) to the class definition for Pool. This patch should also work against the 3.3 branch (though should not be applied to 3.2 as the context manager behavior had not yet been added to Pool in 3.2 -- the example in the intro would need changing for this to be applied to 3.2 is all). ---------- Added file: http://bugs.python.org/file37291/multiprocessing_34.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +sbt stage: -> patch review type: behavior -> enhancement versions: +Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Changes by Davin Potts <python@discontinuity.net>: ---------- nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Raymond Hettinger added the comment: +1 It looks like the relevant information has been preserved while adding an example where the module is being used as designed. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Davin Potts added the comment: Procedural question (wanting to understand the label given to this issue): when documentation does not adhere to the Python Developer's Guide, is a fix for this considered an "enhancement"? ---------- versions: +Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Raymond Hettinger added the comment:
Procedural question ... is a fix for this considered an "enhancement"?
Improvements to documentation are almost always backported. The contrasts with code changes where enhancements (new features, optimizations, or refactorings) are made only on the latest development branch to reduce the risk of destabilizing code that has already shipped. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Roundup Robot added the comment: New changeset a9a9c71f8e15 by Antoine Pitrou in branch '3.4': Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate. https://hg.python.org/cpython/rev/a9a9c71f8e15 New changeset a65c23ea5f9e by Antoine Pitrou in branch 'default': Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate. https://hg.python.org/cpython/rev/a65c23ea5f9e ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Roundup Robot added the comment: New changeset e7d03a33e675 by Antoine Pitrou in branch '2.7': Issue #22952: improve multiprocessing doc introduction and defer notes until appropriate. https://hg.python.org/cpython/rev/e7d03a33e675 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
Antoine Pitrou added the comment: I've committed your patches, Davin. Thank you for contributing! ---------- nosy: +pitrou resolution: -> fixed stage: patch review -> resolved status: open -> closed versions: -Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22952> _______________________________________
participants (5)
-
Antoine Pitrou -
Berker Peksag
-
Davin Potts
-
Raymond Hettinger
-
Roundup Robot