From amyodov at gmail.com Tue Nov 9 14:09:48 2010 From: amyodov at gmail.com (Alex Myodov) Date: Tue, 09 Nov 2010 16:09:48 +0300 Subject: [Doc-SIG] python-dbc (epydoc-based Design-by-Contract validator) Message-ID: <4CD9481C.7040106@gmail.com> Hello, I would like to notify the community about the availability of new python-dbc module, allowing one to perform basic design-by-contract checks using the docstring definitions in epydoc format. No public releases has been done yet, but the home page with overall instructions is created at http://python-dbc.googlecode.com/ and the code is available at https://python-dbc.googlecode.com/hg/ (this is a Mercurial repository, use hg clone). At the moment, the primary functionality available is the validation of @precondition/@postcondition/@type/@rtype docstring fields in every function wrapped using @contract_epydoc decorator. The code is early, lacks a proper amount of unit tests and documentation, and definitely may have bugs for now, but it is stress-tested at the moment in internal projects, so far so good. The future plans include allowing to use the @contract_epydoc decorator to wrap the classes, thus making possible to add the support of @invariant fields in the class docstrings. -- With best regards, Alexander Myodov email: amyodov at gmail.com My LinkedIn page ,^en MoiKrug page ,^ru LiveJournal blog ^ru -------------- next part -------------- An HTML attachment was scrubbed... URL: From skip at pobox.com Wed Nov 24 22:23:02 2010 From: skip at pobox.com (skip at pobox.com) Date: Wed, 24 Nov 2010 15:23:02 -0600 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: <19693.33334.510004.612856@montanaro.dyndns.org> Georg> at , you can look at a version of Georg> the 3.2 docs that has the upcoming commenting feature. Very cool. Georg> Any feedback is appreciated (I'd suggest mailing it to doc-SIG Georg> only, to avoid cluttering up python-dev). It would be nice if you could "invert" things and show comments with links back to the pages/blocks where those comments were made. That would seem to be useful for a documenter who wants to know where all the comments are. Unless you have some hidden interface it seems like you just have to navigate to every page and look for bubbles. Skip From g.brandl at gmx.net Thu Nov 25 08:30:20 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Thu, 25 Nov 2010 08:30:20 +0100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: <19693.33334.510004.612856@montanaro.dyndns.org> References: <19693.33334.510004.612856@montanaro.dyndns.org> Message-ID: Am 24.11.2010 22:23, schrieb skip at pobox.com: > > Georg> at , you can look at a version of > Georg> the 3.2 docs that has the upcoming commenting feature. > > Very cool. Thanks! > Georg> Any feedback is appreciated (I'd suggest mailing it to doc-SIG > Georg> only, to avoid cluttering up python-dev). > > It would be nice if you could "invert" things and show comments with links > back to the pages/blocks where those comments were made. That would seem to > be useful for a documenter who wants to know where all the comments are. > Unless you have some hidden interface it seems like you just have to > navigate to every page and look for bubbles. Yes, that's definitely one thing I had in mind for the moderator side. I'm leaning toward the "don't keep comments endlessly, but fold back good suggestions into the main text" side of things, so a good view of "things to do" is definitely needed. Georg From brian.curtin at gmail.com Fri Nov 26 16:33:52 2010 From: brian.curtin at gmail.com (Brian Curtin) Date: Fri, 26 Nov 2010 09:33:52 -0600 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Wed, Nov 24, 2010 at 14:24, Georg Brandl wrote: > Hi, > > at , you can look at a version of the 3.2 > docs that has the upcoming commenting feature. JavaScript is mandatory. > I've switched on anonymous comments for testing, but usually at least > comments from anonymous users can be moderated. Be sure to test the > "propose a change" feature too. Login currently allows OpenID exclusively. > > Credits go to Jacob Mason, whose GSOC project is responsible for almost all > of what you see there. [1] > > Please test on a smaller page, such as >, > there is currently a speed issue with larger pages. (Helpful tips from > JS experts are welcome.) > > Other things I have to do before this can go live: > > * reuse existing logins from either wiki or tracker? > I would vote for reuse of the tracker login. That way, if a user proposes a change, an issue could be generated from their tracker ID, they'll be nosy, have follow-up input, etc. This way people get a better sense of how their contribution flows along and they'll be included throughout the process. (sorry if I'm repeating anything -- I'm not subscribed to doc-sig) -------------- next part -------------- An HTML attachment was scrubbed... URL: From dreamingforward at gmail.com Fri Nov 26 21:52:01 2010 From: dreamingforward at gmail.com (average) Date: Fri, 26 Nov 2010 13:52:01 -0700 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Wed, Nov 24, 2010 at 1:24 PM, Georg Brandl wrote: > at , you can look at a version of the 3.2 > docs that has the upcoming commenting feature. JavaScript is mandatory. > I've switched on anonymous comments for testing, but usually at least > comments from anonymous users can be moderated. Be sure to test the > "propose a change" feature too. Login currently allows OpenID exclusively. > Credits go to Jacob Mason, whose GSOC project is responsible for almost all > of what you see there. [1] > > Nice job. Other things I have to do before this can go live: > > * reuse existing logins from either wiki or tracker? > +1, Anonymous comments good too... mark -------------- next part -------------- An HTML attachment was scrubbed... URL: From fdrake at acm.org Fri Nov 26 22:28:19 2010 From: fdrake at acm.org (Fred Drake) Date: Fri, 26 Nov 2010 16:28:19 -0500 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Fri, Nov 26, 2010 at 3:52 PM, average wrote: > Anonymous comments good too... I suspect anonymous comments fall into the same category as anonymous issue tracker submissions. We've disallowed those for good reasons, and those make sense in this case as well. For the moderator side of things, I wonder if it makes sense to actually create a tracker issue behind the scenes for each comment; that would take care of the discovery issue for maintainers. ? -Fred -- Fred L. Drake, Jr.? ? "A storm broke loose in my mind."? --Albert Einstein From ncoghlan at gmail.com Sat Nov 27 12:24:15 2010 From: ncoghlan at gmail.com (Nick Coghlan) Date: Sat, 27 Nov 2010 21:24:15 +1000 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake wrote: > On Fri, Nov 26, 2010 at 3:52 PM, average wrote: >> Anonymous comments good too... > > I suspect anonymous comments fall into the same category as anonymous > issue tracker submissions. ?We've disallowed those for good reasons, > and those make sense in this case as well. Are you sure about that? The problem with general tracker submissions is that we almost always need additional information from the original submitter (what version, what platform, does it work if you try version X+1, etc). Opening up anonymous submissions would just mean more work for tracker folks in trying to reproduce the problems, failing and then closing them as "works for me" or "not enough information". None of those reasons apply to doc comments - "this is wrong", "this is unclear and would be better worded as 'make sure to do X before doing Y'" are potentially useful even if the docs editors never hear from the submitter ever again. The key difference is that the doc maintainers don't need to try to reproduce anything - they just read the comment, decide whether or not they agree with it and then either apply it, modify and then apply it, or else deep-six it, never to be seen again. Cheers, Nick. -- Nick Coghlan?? |?? ncoghlan at gmail.com?? |?? Brisbane, Australia From ncoghlan at gmail.com Sat Nov 27 13:05:32 2010 From: ncoghlan at gmail.com (Nick Coghlan) Date: Sat, 27 Nov 2010 22:05:32 +1000 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl wrote: > Hi, > > at , you can look at a version of the 3.2 > docs that has the upcoming commenting feature. ?JavaScript is mandatory. Very nice! I'm not sure what to do about the discoverability of the comment bubbles as the end of each paragraph. I initially thought commenting wasn't available on What's New or the Using Python docs until seeing where the blue comment bubbles appeared in the math module docs. A discreet notice at the bottom of the sidebar and/or an explanation at the "Report a Bug" page may cover it I guess. > Please test on a smaller page, such as , > there is currently a speed issue with larger pages. ?(Helpful tips from > JS experts are welcome.) I gave the JS a fair few comments on the first paragraph to digest. I also put my detailed UI comments there as well (I needed something to write about while testing, so I figured I may as well make it useful to you!) > Other things I have to do before this can go live: > > * reuse existing logins from either wiki or tracker? Tracker sounds like the best bet to me. > Any feedback is appreciated (I'd suggest mailing it to doc-SIG only, to avoid > cluttering up python-dev). My comments may on the math module may give you a chance to see how easy it is to get text out of comments into a form suitable for sending to a mailing list or posting to a tracker issue for further discussion :) Cheers, Nick. -- Nick Coghlan?? |?? ncoghlan at gmail.com?? |?? Brisbane, Australia From g.brandl at gmx.net Sat Nov 27 21:45:55 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Sat, 27 Nov 2010 21:45:55 +0100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: Am 27.11.2010 13:05, schrieb Nick Coghlan: > On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl wrote: >> Hi, >> >> at , you can look at a version of the 3.2 >> docs that has the upcoming commenting feature. JavaScript is mandatory. > > Very nice! > > I'm not sure what to do about the discoverability of the comment > bubbles as the end of each paragraph. I initially thought commenting > wasn't available on What's New or the Using Python docs until seeing > where the blue comment bubbles appeared in the math module docs. > > A discreet notice at the bottom of the sidebar and/or an explanation > at the "Report a Bug" page may cover it I guess. Yeah. I'd rather keep links for uncommented paragraphs hidden by default though; the cluttering is greatly reduced that way. One thing we need to decide is whether to keep the icons at all; maybe a text link (see http://book.realworldhaskell.org/read/ for an example) is more obvious. >> Please test on a smaller page, such as , >> there is currently a speed issue with larger pages. (Helpful tips from >> JS experts are welcome.) > > I gave the JS a fair few comments on the first paragraph to digest. I > also put my detailed UI comments there as well (I needed something to > write about while testing, so I figured I may as well make it useful > to you!) Thanks! :) >> Other things I have to do before this can go live: >> >> * reuse existing logins from either wiki or tracker? > > Tracker sounds like the best bet to me. I'll confer with Martin on this one then. Georg From g.brandl at gmx.net Sat Nov 27 21:47:24 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Sat, 27 Nov 2010 21:47:24 +0100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: Am 27.11.2010 12:24, schrieb Nick Coghlan: > On Sat, Nov 27, 2010 at 7:28 AM, Fred Drake wrote: >> On Fri, Nov 26, 2010 at 3:52 PM, average wrote: >>> Anonymous comments good too... >> >> I suspect anonymous comments fall into the same category as anonymous >> issue tracker submissions. We've disallowed those for good reasons, >> and those make sense in this case as well. > > Are you sure about that? > > The problem with general tracker submissions is that we almost always > need additional information from the original submitter (what version, > what platform, does it work if you try version X+1, etc). Opening up > anonymous submissions would just mean more work for tracker folks in > trying to reproduce the problems, failing and then closing them as > "works for me" or "not enough information". None of those reasons > apply to doc comments - "this is wrong", "this is unclear and would be > better worded as 'make sure to do X before doing Y'" are potentially > useful even if the docs editors never hear from the submitter ever > again. The key difference is that the doc maintainers don't need to > try to reproduce anything - they just read the comment, decide whether > or not they agree with it and then either apply it, modify and then > apply it, or else deep-six it, never to be seen again. I agree. I'd rather put in aggressive spam-filtering than block anonymous comments; this commenting really is about easy and quick feedback rather than an involved process. That said, it really depends on how people are using the comment feature once it's in place. If we see too many unqualified or nonsense comments from anonymous users, we can still decide to block them. Georg From steve at pearwood.info Sat Nov 27 23:11:44 2010 From: steve at pearwood.info (Steven D'Aprano) Date: Sun, 28 Nov 2010 09:11:44 +1100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: <4CF18220.7000202@pearwood.info> Nick Coghlan wrote: > On Thu, Nov 25, 2010 at 6:24 AM, Georg Brandl wrote: >> Hi, >> >> at , you can look at a version of the 3.2 >> docs that has the upcoming commenting feature. JavaScript is mandatory. > > Very nice! > > I'm not sure what to do about the discoverability of the comment > bubbles as the end of each paragraph. I initially thought commenting > wasn't available on What's New or the Using Python docs until seeing > where the blue comment bubbles appeared in the math module docs. I wonder what the point of the comment bubbles is? This isn't a graphical UI where (contrary to popular opinion) a picture is *not* worth a thousand words, but may require a help-bubble to explain. This is text. If you want to make a comment on some text, the usual practice is to add more text :) I wasn't able to find a comment bubble that contained anything, so I don't know what sort of information you expect them to contain -- every one I tried said "0 comments". But it seems to me that comments are superfluous, if not actively harmful: (1) Anything important enough to tell the reader should be included in the text, where it can be easily seen, read and printed. (2) Discovery is lousy -- not only do you need to be running Javascript, which many people do not for performance, privacy and convenience[*], but you have to carefully mouse-over the paragraph just to see the blue bubble, and THEN you have to *precisely* mouse-over the bubble itself. (3) This will be a horrible and possibly even literally painful experience for anyone with a physical disability that makes precise positioning of the mouse difficult. (4) Accessibility for the blind and those using screen readers will probably be non-existent. (5) If the information in the comment bubbles is trivial enough that we're happy to say that the blind, the disabled and those who avoid Javascript don't need it, then perhaps *nobody* needs it. [*] In my experience, websites tend to fall into two basic categories: those that don't work at all without Javascript, and those that run better, faster, and with fewer anti-features and inconveniences without Javascript. -- Steven From steve at pearwood.info Sun Nov 28 00:58:52 2010 From: steve at pearwood.info (Steven D'Aprano) Date: Sun, 28 Nov 2010 10:58:52 +1100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: <4CF18220.7000202@pearwood.info> Message-ID: <4CF19B3C.2000308@pearwood.info> Georg Brandl wrote: > Am 27.11.2010 23:11, schrieb Steven D'Aprano: >> I wasn't able to find a comment bubble that contained anything, so I >> don't know what sort of information you expect them to contain -- every >> one I tried said "0 comments". > > Maybe you should have tried the page I recommended as a demo, and where Nick > made his comments? :) Aha! I never would have guessed that the bubbles are clickable -- I thought you just moused-over them and they showed static comments put there by the developers, part of the documentation itself. I didn't realise that it was for users to add spam^W comments to the page. With that perspective, I need to rethink. Yes, I failed to fully read the instructions you sent, or understand them. That's what users do -- they don't read your instructions, and they misunderstand them. If your UI isn't easily discoverable, users will not be able to use it, and will be frustrated and annoyed. The user is always right, even when they're doing it wrong *wink* >> But it seems to me that comments are superfluous, if not actively harmful: > > (I've not read anything about harmful below. Was that just FUD?) Lowering accessibility to parts of the documentation is what I was talking about when I said "actively harmful". But now that I have better understanding of what the comment system is actually for, I have to rethink. -- Steven From steve at pearwood.info Sun Nov 28 01:43:48 2010 From: steve at pearwood.info (Steven D'Aprano) Date: Sun, 28 Nov 2010 11:43:48 +1100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: <4CF1A5C4.9060306@pearwood.info> Georg Brandl wrote: > Hi, > > at , you can look at a version of the 3.2 > docs that has the upcoming commenting feature. JavaScript is mandatory. > I've switched on anonymous comments for testing, but usually at least > comments from anonymous users can be moderated. Be sure to test the > "propose a change" feature too. Login currently allows OpenID exclusively. Testing as an anonymous user with Konqueror 3.5.9 ================================================= I can show comments, and add them, but I can't hide them once shown. Once I add a comment, the UI for adding a comment (text field and Add A Comment button) disappears. "Propose a change" doesn't work for me *at all* -- it just scrolls to the top of the page. Likewise for the "sort by" links, the "markup" links and the Vote Up and Vote Down buttons. There are no "Reply" and "Proposal" controls visible. Testing with Epiphany ("Gnome Web Browser") 2.18.3 ================================================== The text field and Add A Comment button also disappear after adding a comment. Hiding the comment block and re-showing it makes it return. The sort by and markup links seem to work. The threading model is unintuitive and strange -- if I reply to a comment, the reply doesn't show up anywhere near the comment I replied to. I would suggest that proposals should be visible by default. The algorithm used to highlight changes in proposals is counter-intuitive. For example, I proposed a change to this text: factorial. Raises :exc:`ValueError` if *x* is not integral or is negative. by inserting the word "interestingly" before "integral": factorial. Raises :exc:`ValueError` if *x* is not interestingly integral or is negative. This was highlighted as: factorial. Raises :exc:`ValueError` if *x* is not inteRESTINGLY INTEgral or is negative. instead of the more intuitive: factorial. Raises :exc:`ValueError` if *x* is not INTERESTINGLY integral or is negative. Performance really is poor :( There is a noticeable lag on even hiding and showing the smallest thing. -- Steven From fdrake at acm.org Sun Nov 28 05:09:26 2010 From: fdrake at acm.org (Fred Drake) Date: Sat, 27 Nov 2010 23:09:26 -0500 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: Message-ID: On Sat, Nov 27, 2010 at 6:24 AM, Nick Coghlan wrote in response to my comment about anonymous comments: > Are you sure about that? I'm quite certain. Experience will tell whether I'm right, of course. > The problem with general tracker submissions is that we almost always > need additional information from the original submitter (what version, > what platform, does it work if you try version X+1, etc). Opening up > anonymous submissions would just mean more work for tracker folks in > trying to reproduce the problems, failing and then closing them as > "works for me" or "not enough information". Right. > None of those reasons > apply to doc comments - "this is wrong", "this is unclear and would be > better worded as 'make sure to do X before doing Y'" are potentially > useful even if the docs editors never hear from the submitter ever > again. Bug reports are also *potentially* useful even without further information from the OP. It may well contain enough information. Doc comments saying "this is unclear" or "this is wrong" can easily trigger a request for clarification: "What more did you want to know?" "Why do you think this is incorrect?" > The key difference is that the doc maintainers don't need to > try to reproduce anything - they just read the comment, decide whether > or not they agree with it and then either apply it, modify and then > apply it, or else deep-six it, never to be seen again. A comment that says the doc is wrong may well trigger an attempt to use the API in question, and confusion because the comment didn't include enough information to identify the specific can the OP is really talking about. ? -Fred -- Fred L. Drake, Jr.? ? "A storm broke loose in my mind."? --Albert Einstein From g.brandl at gmx.net Mon Nov 29 09:59:49 2010 From: g.brandl at gmx.net (Georg Brandl) Date: Mon, 29 Nov 2010 09:59:49 +0100 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: <4CF1A5C4.9060306@pearwood.info> References: <4CF1A5C4.9060306@pearwood.info> Message-ID: Am 28.11.2010 01:43, schrieb Steven D'Aprano: > Georg Brandl wrote: >> Hi, >> >> at , you can look at a version of the 3.2 >> docs that has the upcoming commenting feature. JavaScript is mandatory. >> I've switched on anonymous comments for testing, but usually at least >> comments from anonymous users can be moderated. Be sure to test the >> "propose a change" feature too. Login currently allows OpenID exclusively. > > Testing as an anonymous user with Konqueror 3.5.9 > ================================================= > > I can show comments, and add them, but I can't hide them once shown. > > Once I add a comment, the UI for adding a comment (text field and Add A > Comment button) disappears. That is intended. I don't think many users will want to leave multiple comments at one time, and I put in that feature to actively discourage Columbo-style commenting. The field can always be brought back by re-opening the comment popup. > "Propose a change" doesn't work for me *at all* -- it just scrolls to > the top of the page. > > Likewise for the "sort by" links, the "markup" links and the Vote Up and > Vote Down buttons. > > There are no "Reply" and "Proposal" controls visible. That is all noted, looks like I'll have to test the UI more with Konqueror. > > Testing with Epiphany ("Gnome Web Browser") 2.18.3 > ================================================== > > The text field and Add A Comment button also disappear after adding a > comment. Hiding the comment block and re-showing it makes it return. > > The sort by and markup links seem to work. The threading model is > unintuitive and strange -- if I reply to a comment, the reply doesn't > show up anywhere near the comment I replied to. That is a bug and needs to be fixed. > I would suggest that proposals should be visible by default. The problem is that they take a *lot* of space. But it needs to be more visible that there *is* a proposal. > The algorithm used to highlight changes in proposals is > counter-intuitive. For example, I proposed a change to this text: > > factorial. Raises :exc:`ValueError` if *x* is not integral > or is negative. > > by inserting the word "interestingly" before "integral": > > factorial. Raises :exc:`ValueError` if *x* is not > interestingly integral or is negative. > > This was highlighted as: > > factorial. Raises :exc:`ValueError` if *x* is not > inteRESTINGLY INTEgral or is negative. > > instead of the more intuitive: > > factorial. Raises :exc:`ValueError` if *x* is not > INTERESTINGLY integral or is negative. That's difflib for you. I don't really want to roll my own here. > Performance really is poor :( There is a noticeable lag on even hiding > and showing the smallest thing. A bit of lag is expected when loading comments, but inside the comment popup everything should be smooth. I know of problems with large pages, but if it's slow even on the math page, it seems that that browser is really behind in terms of JavaScript optimizations... Thanks for testing, Georg From alexander.belopolsky at gmail.com Mon Nov 29 17:07:03 2010 From: alexander.belopolsky at gmail.com (Alexander Belopolsky) Date: Mon, 29 Nov 2010 11:07:03 -0500 Subject: [Doc-SIG] [Python-Dev] [Preview] Comments and change proposals on documentation In-Reply-To: References: <4CF18220.7000202@pearwood.info> <4CF19B3C.2000308@pearwood.info> Message-ID: On Mon, Nov 29, 2010 at 3:52 AM, Georg Brandl wrote: .. >> Yes, I failed to fully read the instructions you sent, or understand >> them. That's what users do -- they don't read your instructions, and >> they misunderstand them. If your UI isn't easily discoverable, users >> will not be able to use it, and will be frustrated and annoyed. The user >> is always right, even when they're doing it wrong *wink* > > That's right, of course. ?I really come to the conclusion that having a text > link that "looks like" a link, i.e. is underlined, will have a better UI > experience (since we cannot put notes "click bubble to comment" everywhere). > Please don't make comment bubbles more visible. Doing so will only decrease signal to noise ratio. I think a little bit of a learning barrier is a good thing: it will keep down the number of "Bart was here" comments.