Last year was a busy one for PyCon tutorial and talk presenter Brandon Rhodes. His conference trips took him from Santa Clara to his home state of Ohio and up to Toronto, with talks at all of them. PyCon was particularly busy with two tutorials as well as two talks, going with single talks at PyOhio and PyCon Canada later in the year. He also made a busy 2011 for himself with three talks at PyOhio in 2011 after his PyCon tutorial, and gave great dictionary talk the year before at PyCon 2010 with the tutorial that started it all. Save for the tutorials, you can check out those presentations on pyvideo.
He’s kicking 2013 off right with a redux of his well received “Documenting Your Project in Sphinx” tutorial, giving its fourth run on Thursday March 14 at 9 AM. Started at PyCon 2010 in Atlanta, the tutorial introduces the widely used Sphinx documentation framework, a staple of the Python community. Sphinx lets you focus on writing great documentation rather than inundating the writer with all sorts of presentation details. The powerful framework is hard at work powering Python’s own documentation at http://docs.python.org/.
Brandon uses a presentation style he dubs “lightning lectures”, where he gives a small lecture on a particular topic, then immediately gets the attendee into an example. New for this year is a streamlining of the exercises, where instead of having attendees make up documentation on the fly, they’re provided with pre-written text, allowing them to focus their efforts on the Sphinx features they just learned.
Two new topics were added for the 2013 edition, both of which are worth the price of admission for anyone getting started towards better documentation. Brandon will be working in some examples of theming to style up your documentation, and deployment to the popular Read The Docs Sphinx hosting service gets some well deserved coverage.
I asked Brandon about the popularity of RTD and its addition to this year’s course, and he was ecstatic to be introducing it. “I think that hosting is only half of the reason for its popularity: the other reason is how simply it integrates into a project's version control system, where commits on GitHub can automatically cause the documentation to be rebuilt on Read The Docs!”
“The tutorial really tries to describe how documentation in text files under version control can integrate with a live project,” he said to describe the course. Organization is key when it comes to documentation, and he covers Sphinx’s layout “in a way that makes sense to people using the library for the first time, as well as for people who are quite experienced with the software but need to look something up.”
He’s also taking the stage for a talk on Friday morning at 10:50, titled “The Naming of Ducks: Where Dynamic Types Meet Smart Conventions”. “I sometimes see snide comments from static language folks about how Python code is unreadable because you never know the types of any of your variables,” he said of how the topic came up. Through this talk he hopes to dispel the unreadability myth by showing the conventions Python programmers use and how they affect the utility of a name. “Variable names in Python are not throw-away; they are our lifeline, that make it possible to read each other's code, and to read our own code months later,” he exclaimed.
Be sure to check out Brandon’s talk on Friday and sign up for his Sphinx tutorial on Thursday at https://us.pycon.org/2013/registration/. Although the conference is sold out, tutorials are still accepting registrations for the low price of $150 per session. That gets you three hours of learning from some of the best educators in the Python world, and includes lunch and a snack break. It’s really worth it, so check out the schedule: https://us.pycon.org/2013/schedule/tutorials/.
Check out what Brandon’s up to on twitter at @brandon_rhodes and take a look at his recent open source project, Skyfield, a really cool astronomy tool. PyCon is happy to have him back again for another year and we hope you enjoy his presentations as well as all of the others on our schedule.