I've put up a copy of Commentary in front of the Python 2.4 documentation at http://pythonpaste.org/comment/python24/
This is kind of a test, to see whether the particulars of Commentary can fit the needs for the Python documentation. People have been asking for the Python documentation to have comments for a long time. So, here's some a system that allows that, see if you think it feels right. But if you leave long and involved comments, it's possible no one will see them. (Well, if there really are good comments and I shut this off, I'll try to pass those comments upstream.)
Feedback welcome, preferred as trac tickets.
I made a note on http://pythonpaste.org/comment/python24/lib/module-logging.html Had to click the ? to figure out how, but the interface was groovy thereafter.
Wow Ian, it looks really good, but I do have my doubt about the per paragraph commenting. Won't more than 4 or 5 comments on a single paragraph completely ruin the layout of the page?
great work!
It can be difficult for the layout. They should just extend downward, but it gets bad when there's lots of comments on one paragraph, and then a comment on the next paragraph. That's ugly. The folded view might be better, or maybe some overflow thing, or otherwise combining comments. Really long comments (which can be very useful) will also cause these problems.
I also want to add a better interface for commenting on the entire page, probably presented as a simple list of comments at the end of the page. Or maybe threaded.
# Ian Bicking
Great idea!
I started looking through the Tutorial, and came a cropper on this page: http://pythonpaste.org/comment/python24/tut/node5.html The long and colorful traceback ends with UnicodeEncodeError: 'ascii' codec can't encode characters in position 18864-18866: ordinal not in range(128)
Yeah, someone (perhaps you) submitted a ticket on that too. I thought I was decoding stuff properly (the Python docs are ISO-8859-1), but apparently I put the configuration in for that without actually implementing it.
# Ian Bicking
Ian, you rock! I didn't check the source code, but at least the visual appeal is incredible!
Thanks!
Indeed, it is amazing! I think this will be most helpful for adding examples in the library section -which I find very dry-. Thanks for this excellent work! I hope it gets "promoted" to the official docs.
# Ismael
Great site, keep up the good work!
asesoe