Pocco: Another Take on Documentation

I just discovered a cute tool called pocco on github. Apparently pocco is the Python version of what is also known as docco, rocco, and (gasp) shocco out there. Quite the zoo really! :-D So what does it do? It parses Python source and separates comments from code. It then dumps everything into HTML with a little CSS, making the comments appear on the left lined up with the corresponding code on the right. Neato.

Or it is? What could this possibly be useful for? Comments in Python are not usually used for documentation: we have docstrings after all! But docstrings are not perfect, for example you can only (by "natural" means anyway) attach a docstring to a module or class or function: What about those globals over there? Do I really have to document them in the module docstring?

But I realized that something like pocco is actually useful in Python. After all, the documentation you put into a docstring should be concise and clean: it should say exactly what it needs to say for someone else to use your stuff, nothing else. Boring! What about all those humorous anecdotes you accumulate while you hack? What about false starts, things that others should be told about before they head down the same wrong way. And so on, and so forth. With pocco, you can use comments for commentary and docstrings for documentation yet extract and (nicely?) format both. How cool is that? :-D Let's just hope that pocco will leave docstrings alone for good...

The other use I could come up with is code handouts in programming courses. Often the comments I write in this context have more of a "let me take you by the hand and work this through with you" feeling. Reading them in a nicely formatted and syntax-highlighted way may be nicer for everyone involved. True, since all comments are extracted it's hard to "comment on comments" that way... But that's okay, at least for me. Now all I need for this second application is Java, C, and C++ support! :-D

Know one editor well...

For years I've been telling people new to Unix that it doesn't matter what editor they pick. "Just pick one and learn it well!" I still believe that's true, but I've recently come to realize that I may not have followed my own advice in this regard.

I've been using vi (well vim) for years, yet apparently I have not even come close to exploiting it like I should have. Here are a few links to get you started. Take a look even if you think you know vim well, you may be surprised what it has to offer these days.

Efficient Editing with vim
Automatic Word Completion
vimsh
Indenting Python with vim
Python and vim: Make your own IDE
Vim as Development Environment
Code Navigation and Completion
Vim as Python IDE

Obviously I am focused on Python here because that's what I hack the most for my personal projects, but much of the information is applicable regardless of what language (programming or otherwise) you have to work with every day. I still can't believe that I missed out on many of these options for years. Don't make the same mistake! :-D

su, sudo, and /dev/pts/*

I have a few separate accounts even on my own local machine just to organize things slightly differently for different projects I am working on. Let's call my standard account "s" and one of the other accounts "q". When my machine starts up, I log in as "s", then when I need to work as "q" I use su - q to switch. Seemed like a good idea at the time.

The problem is that /dev/pts/* is owned by "s" since apparently it gets created when "s" first logs in. Now as "q" I can't use things like /dev/stdin or run screen because the permissions on /dev/pts/* are not "permissive" enough. I could probably find a way to open up the permissions, but that doesn't seem quite right. What I really want is to have "q" create it's own /dev/pts/* owned by "q".

For the longest time I couldn't find a way to get this done. Then yesterday it occurred to me to try sudo login instead of su - q and that actually works! You can't do login by itself, it'll complain, but sudo login seems fine. So my problem is apparently fixed, although now I do wonder if there are any security problems with my new approach to switching users. Anyone?

POSSE Worcester, Day 5

With a small delay, here the summary of Day 5. First we moved to another building since the Science and Technology Center was undergoing some kind of loud demolition. :-( We hacked for a little while and then Walter talked about what to do over the next few days and how to push when we're done and do the merge request. Since I had not done much on the Measure activity but on Physics instead, I wasn't very affected by this.

Then we had our huge teaching chat, which started with Garry demonstrating what he's doing at WPI with his Software Engineering course. After that "semi-formal" part it was just open discussion. Mel wanted to make things more concrete, so she started a transcript on Pirate Pad that we all edited furiously for about 40 minutes or so. Then we went over the transcript with more discussion. And then we were done. :-D

Some people left at this point, but some of us gathered around and went to Karl's favorite Hot Dog place which was quite the treat. I had three Cony Island Dogs (trust me, they are kinda small :-D), a Chilli Cheese burger, and two "dry" Orange sodas. The only drawback was that they didn't have a booth for five, so I was a bit lonely. :-( But on one of my breaks I found a sticker outside that had the picture of a guy on it and said "Pickels, 5' 10", 160 lbs. has a posse" and that made us smile. :-D

I went back to my hotel and made the mistake (or was it one?) of youtubing around. Ended up watching "The Last Lecture" again, wow. So I showed up for the final dinner with Mel and Peter a little teary-eyed, but I don't think they noticed. We went to the Brazilian Steak House I wanted to check out the first night, and guess what? It was absolutely delicious (and none of us "smelled like meat" afterwards, Mihaela :-D)!

In summary, I had a great week at POSSE in Worcester, and I'd like to thank everybody who was there for making it such a very, very cool event. Oh, and Mihaela posted some photos, thank you so much for that too!

POSSE Worcester, Day 4

Day 4 started badly because I couldn't wake up on time. While I got on IRC to tell people not to wait for me, Mel is just too nice and waited anyway. So I held everybody up for about an hour. :-(

We did some more specialized discussions in smaller groups before lunch. Mihaela and I were walked through the details of the translation process as used in the Sugar project by Walter. I had used the web interface to this before to do some translations, but it was good to hear it all in context. (Future students beware: Walter convinced me that I can actually add this to a C course as well, given that gettext is completely pervasive on GNU systems. :-D)

I didn't have too much success with code, so I just did some more translation work before lunch. Lunch was at the WSC cafeteria again, I am still amazed at how good the food is there (for a university outfit). I just wish JHU would get their stuff together in this regard.

After lunch we were supposed to have a few more "split into groups" things but we actually got "distracted" (in a good sense) by Heidi, a guest from another local college. At first we just wanted to do a round of introductions, but this quickly diverged into a long discussion of how to put FOSS to use in the classroom (which is also the topic for the last day I think).

Mel then went into an overview/review of the various pieces of infrastructure for FOSS projects. I mentioned doodle.com but I held back on recommending github.com (I still think they have the best "basic" setup right now, but I might be wrong). I think I'll start using IRC more in the future, Mel pointed out that "being overheard" in a public chat is a Good Thing (tm) and I believe that's true.

Since it was "dinner night" many of us stayed on campus late. I went back to the Physics activity, desperately looking for something to fix in my favorite piece of Sugar. And I found something: The "grab and move" feature only worked with the simulation running, but not when the simulation was paused. Walter agreed that it should work, so I started hacking on that but didn't get far by myself. Luckily Mihaela stopped by and we started working on it together, and after a few hours we actually figured some of the pieces out. I started reading some of the library source code which promptly helped unravel the last mystery, and we got basic grabbing working before dinner.

The restaurant was somewhat hard to find, but it was certainly worth it as it seems to be somewhat of an "institution" in Worcester. The food was great, and we met "Michael" who works at Akamai and hacks on Sugar every now and then, our "special guest" for the night. Good food, good conversations, good beer, it was a fun evening.

After dinner I finished the patch for Physics and sent it off to the maintainer. I wasn't quite happy with it, but at least I had something to contribute. Gary emailed back pretty quickly that they were looking for that feature for a while, which provided additional motivation to make it better. The problem with my solution thus far was that you didn't get to move an object directly. Instead you clicked on it and then dragged a line to the future position you wanted; when you released the mouse button, the object would "pop" into its new place. It was actually quite straightforward (well, except for one synchronization issue :-D) to get a real "direct manipulation" drag to work, so I sent off another patch to Gary an hour later. I went to bed quite happy with myself for a change. :-D

POSSE Worcester, Day 3

It's frustration day. I should have known that things were going too well when I got up this morning. :-D The day was dedicated to hacking on the Measure activity. I was still using Debian on my netbook and had a hard time following Walter's advice of using the special sugar-jhbuild system to setup a working version of the Sugar emulator. So I checked the Debian packages, and sure enough they offered Sugar! I installed it and all it's dependencies only to find my system completely hosed on the next reboot. So that's awkward dear Debian maintainers. :-(

Seeing as I was in a room full of Fedora machines and Redhat people (well, maybe not so many Redhat people :-D), I begged Mel to make me a Fedora 13 install USB stick. I spent all my time before lunch reinstalling from scratch (and losing my ssh-keys in the process since the encrypted file system I was using under Debian couldn't be recovered properly). And guess what Debian? Under Fedora 13 my sound works just fine, even the microphone; I wonder what I'll find when I try out wireless networking later...

Over lunch Walter mentioned looking into making the display for Measure scrolling. So once we got back from eating I looked at the code for this. I actually got scroll bars wrapped around the display just fine, but then it occurred to me that data was coming in way to fast for the scrolling to be very useful without further additions. So I scrapped that and decided to simply look for Python code to refactor so I would achieve something (anything!) at all. That's still pending, but I did a first pass through most of the code and cleaned up indentation problems as well as unused imports and stuff. But it certainly wasn't a very satisfying day.

Until maddog showed up that is. :-D Jon gave a wonderful pitch for FOSS to our audience of teachers. And even though some of his jokes backfired a little, overall I was very happy to be there and hear him talk. I think we'll have beers in a few, so I look forward to that just like every evening, but especially today since I want to ask Jon a few more things, for example about the "proper" ownership model for basic infrastructure like phone lines. :-D

POSSE Worcester, Day 2

Today was all about hacking. First Walter went over the basic commands for git, then we started working on his Abacus activity. Walter suggested adding a new kind of Abacus, but I saw a piece of code that was repeated like 10 times in a row and decided to replace that with a loop instead. Yeah, I don't follow instructions well... :-D But hey, now I left my (very small) stamp on a piece of free software that others actually work on as well, not too shabby!

The lucky thing about the Abacus was that it runs fine outside of Sugar. I like Sugar in principle, but I don't want to hack inside its unusual confines: I want my actual Unix system! The activity we picked for the homework tonight, Measure, sadly doesn't run outside of Sugar. I played with Physics a bit too, but couldn't get that to work well outside of Sugar either. Also there are a few Physics forks, some of which work better in Gnome than others. Sadly mainline doesn't work well at all. :-( So I am not too sure what to work on tonight, but maybe I'll just keep working on Abacus instead. :-D

I had a great experience with IRC today: I actually got help from a complete stranger! We have a "side task" not related to code, and I picked translating some leftover strings from the Measure activity to German. But the registration for translate.sugarlabs.org was borked for a while this afternoon (has been fixed since). Luckily one of the admins was around and approved my account without the confirmation email that never got to my gmail.com inbox. Of course now that they fixed stuff, I finally got the email. :-D

I am looking forward to having dinner again tonight with the other three people who are stranded in Worcester hotels: Kristina, Mihaela, and Peter (yes, another one!). Last night we had some delicious Mexican food, and tonight I believe we're all going to "smell like meat" (to quote Mihaela) when we roll around in Brazilian BBQ. :-D

Update: Actually, we went to a place called Brew City and they had Bavarian beer: Ayinger! I don't usually drink that, but I had to have two bottles even at $8.50 a pop (wow). Very good stuff, and the food was decent too!

POSSE Worcester, Day 1

Just a quick note that we got started with POSSE today. Yay! We all introduced each other and why we're here, then Mel gave an overview of FOSS development and Walter introduced Sugar, the project we'll be working on for the rest of the week.

The exercises came next, so I now have even more accounts to keep track off: bugs.sugarlabs.org, git.sugarlabs.org, wiki.sugarlabs.org, admin.fedoraproject.org, and bugzilla.redhat.com. I even have a user page on the Sugarlabs wiki, courtesy of Karl. :-D

Lunch at Worcester State College was amazing, possibly the best Chilli I've had on any campus anywhere. At least outside of Texas anyway!

On a more serious note, Walter got me thinking about the Python course I am designing for next Fall. Seems that Sugar may actually be a very good environment to start people out in. It seems to offer a path that gradually introduces more Python and de-emphasizes Sugar, at least if I understand it correctly. Not sure if that should be called "Lighter" then? :-D I'll play with Sugar much more this week, so I'll certainly find out whether it's a good fit by Friday.