Mailman 3 July 2014 - docs

[issue10225] Fix doctest runable examples in python manual
by Andy Maier July 3, 2014

July 3, 2014

Andy Maier added the comment: Hi, I would like to revive this issue and have added a review comment to issue10225-py3k.diff. Otherwise, I have reviewed the changes in both diffs and think they are good to go. Andy ---------- nosy: +andymaier _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10225> _______________________________________

1 0

Fix doctest runable examples in python manual (issue 10225)
by andreas.r.maier＠gmx.de July 3, 2014

July 3, 2014

Hi, I would like to revive this issue and have added the following comment to Lib/collections.py within issue10225-py3k.diff: The \n at the end of this line (and others in this docstring) is used to create an empty line after this line. Is there a reason to use \n instead of simply having the empty line? That makes it more readable. Otherwise, I have reviewed the changes in both diffs and think they are good to go. Andy http://bugs.python.org/review/10225/diff/1884/Lib/collections.py File Lib/collections.py (right): http://bugs.python.org/review/10225/diff/1884/Lib/collections.py#newcode294 Lib/collections.py:294: '%(typename)s(%(argtxt)s)'\n The \n at the end of this line (and others in this docstring) is used to create an empty line after this line. Is there a reason to use \n instead of simply having the empty line? That makes it more readable. http://bugs.python.org/review/10225/

1 0

[issue11389] unittest: no way to control verbosity of doctests from cmd
by anatoly techtonik July 2, 2014

July 2, 2014

New submission from anatoly techtonik <techtonik(a)gmail.com>: I can't find a way to execute DocTests contained in a separate README.txt file using unittest.main() function. That doesn't allow to control verbosity for debugging. I am doing it this way in the tests.py import doctest import unittest if __name__ == '__main__': runner = unittest.TextTestRunner() runner.run(doctest.DocFileSuite('README.txt', optionflags=doctest.ELLIPSIS)) I could find a way to subclass TestLoader.loadTestsFromNames() by looking at the source code of undocumented TestProgram. I'd like to see this use case at least covered by documentation if not properly developed for stdlib of Python4. ---------- assignee: docs@python components: Documentation, Tests messages: 130001 nosy: docs@python, techtonik priority: normal severity: normal status: open title: unittest: no way to control verbosity of doctests from cmd _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11389> _______________________________________

4 6

[issue19024] Document asterisk (*), splat or star operator
by anatoly techtonik July 2, 2014

July 2, 2014

New submission from anatoly techtonik: I'd say this is a critical documentation bug that leads to head bang when you try to figure out what does '*' in code means. This bug is two fold: 1. Define a dedicated place in documentation for '*' operator with examples. I propose http://docs.python.org/3/library/stdtypes.html chapter with a name like "Special Operations" or "Function Argument Operations" or "Function Argument Operators" 2. Make '*', 'asterisk', 'splat', 'star' operator searchable http://docs.python.org/3/search.html?q=* http://docs.python.org/3/search.html?q=asterisk http://docs.python.org/3/search.html?q=splat http://docs.python.org/3/search.html?q=star+operator Good? References: http://stackoverflow.com/questions/2322355/proper-name-for-python-operator http://stackoverflow.com/questions/5239856/foggy-on-asterisk-in-python http://stackoverflow.com/questions/2921847/python-once-and-for-all-what-doe… http://stackoverflow.com/questions/287085/what-do-args-and-kwargs-mean http://stackoverflow.com/search?q=[python]+%2Bkwargs+is%3Aquestion ---------- assignee: docs@python components: Documentation messages: 197772 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Document asterisk (*), splat or star operator type: crash versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19024> _______________________________________

9 14

[issue21908] Grammatical error in 3.4 tutorial
by Jeremy Fusco July 2, 2014

July 2, 2014

New submission from Jeremy Fusco: https://docs.python.org/3/tutorial/controlflow.html Sentence states 'most such' where either would suffice. current: In most such cases, however, it is convenient to use the enumerate() function, see Looping Techniques Proposed: In most cases ---------- assignee: docs@python components: Documentation messages: 222120 nosy: Jeremy.Fusco, docs@python priority: normal severity: normal status: open title: Grammatical error in 3.4 tutorial type: enhancement versions: Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21908> _______________________________________

2 2

[issue14097] Improve the "introduction" page of the tutorial
by Ezio Melotti July 2, 2014

July 2, 2014

New submission from Ezio Melotti <ezio.melotti(a)gmail.com>: I was reading the "introduction" page of the tutorial [0], and noticed a few things that could be improved: 1) the first paragraph is a bit confusing, showing a simple example and explaining what the >>> is would be better; 2) comments can be introduced later too, they are not really necessary at the beginning; 3) the first example is supposed to introduce numbers and basic operations, but it's still going on with the comments; 4) the note about floating point issues is not so relevant anymore nowadays, so it could be (re)moved; 5) "A value can be assigned to several variables simultaneously:" is not technically correct; 6) "Variables must be “defined” (assigned a value) before they can be used" this might be improved too; 7) almost half of the section about numbers goes on explaining complex numbers. This is totally unnecessary here, I think that mentioning them and maybe showing a simple example is more than enough. Another option is to make a subsection with a note that says that the section can be skipped; 8) the examples in this part lack some space (e.g. "a=3.0+4.0j"); 9) the print() function could get a better introduction and used in the first set of string examples; 10) suggesting to use continuation lines with a trailing \ in string literals is not a good idea, it's better to use """...""" or implicit concatenation inside (); 11) "Degenerate slice indices are handled gracefully" it might be better to show that it's not the same for "non-slice" indices; 12) the "About Unicode" section could link to the Unicode HOWTO; 13) while it's true that lists can contain different types of object, they usually shouldn't; 14) while the "while" example is good (it first shows a piece of code and then explains what it does), I would introduce the "if" and the "for" first. The "while" is arguably the most complex and less used of the three statements. [0]: http://docs.python.org/py3k/tutorial/introduction.html ---------- assignee: docs@python components: Documentation messages: 154051 nosy: docs@python, eli.bendersky, eric.araujo, ezio.melotti, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Improve the "introduction" page of the tutorial type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14097> _______________________________________

11 35

ctypes Module Documentation Bug
by Martin Miller July 2, 2014

July 2, 2014

There's a long standing error in one of one examples in section 16.17.2.4 Function Prototypes <https://docs.python.org/3/library/ctypes.html?highlight=ctypes#function-pro…> of the documentation for the ctypes module. It's where there's an example demonstrating how to wrap the Windows MessageBoxA function. Please see stackoverflow.com question titled /The ctypes wraps “MessageBoxA” example didn't work in python33/ <http://stackoverflow.com/questions/18164994/the-ctypes-wraps-messageboxa-ex…> for more details and a possible fix. -- Martin

2 1

[issue12600] Add example of using load_tests to parameterise Test Cases
by Jean-Paul Calderone July 2, 2014

July 2, 2014

Changes by Jean-Paul Calderone <jean-paul(a)hybridcluster.com>: ---------- nosy: -exarkun _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12600> _______________________________________

1 0

[issue21902] Docstring of math.acosh, asinh, and atanh
by Mark Dickinson July 2, 2014

July 2, 2014

Mark Dickinson added the comment: Kevin: does the attached patch look okay to you? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21902> _______________________________________

2 1

[issue21902] Docstring of math.acosh, asinh, and atanh
by Ezio Melotti July 2, 2014

July 2, 2014

Ezio Melotti added the comment: >> https://docs.python.org/3/library/math.html#hyperbolic-functions should be updated as well. > > It looks fine to me. What do you think should be changed? I just meant to say that the docs and the docstrings should be kept in sync (especially if they are short like in this case). If the definition in the docs is better it could be used for the docstrings; if something gets improved in the docstring that is not already in the docs it should be added to the docs as well. If either one is fine there's no need to update it. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21902> _______________________________________

1 0