Marc-Andre Lemburg added the comment: On 13.09.2013 22:23, R. David Murray wrote: > > R. David Murray added the comment: > > Just to be clear: the reason I am opposed is that the audience for Misc/NEWS > is different from the audience for commit messages, and I would prefer that > the text reflect that. Mine do :)
I'm with David and -1 on auto-generating documentation that is meant for Python users. Here's my take on the intentions behind the various forms of documentation we have: * Commit messages only provide a very terse hint at what a particular patch set was meant for. The target audience is other core developers. * News entries explain these patches (there may be more than one for a particular issue or project) to Python programmers who need to know what to watch out for when upgrading to a new version. * The "What's New" document explains the reasoning and effects of major changes and gives a high level overview of what to expect in a new version. * Finally, the Python documentation, with it's "Version added" markers, provides details to application programmers who need to know how the new techniques work and when they were added (in order to determine which APIs they can use if they want to support multiple Python versions). ---------- nosy: +lemburg _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue18967> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com