Sphinx - the ultimate tool for documenting your software project

*
Accepted Session
Short Form
Scheduled: Thursday, June 3, 2010 from 2:30 – 3:15pm in Fremont

Excerpt

Open source software projects can succeed or fail based on their documentation. Thanks to Sphinx, open source developers now have a "documentation framework" that provides convenient indexing and automatic syntax highlighting, integrates your documentation with your code, and can automatically generate a beautiful manual as a PDF document.

Description

Sphinx makes documenting your project almost too easy.

You can even integrate your documentation with your code in that your documentation can be run as a test, and your class and function docstrings can become your reference documentation.

Markup as well-designed as reStructuredText is not only a lot of fun to use, but it also very cleanly separates content from design. Authors working in plain text tend to produce clean, readable content without the messy markup often associated with visual HTML editors, or, worse yet, the disaster that is Microsoft Word.

Sphinx is written in Python, but you can use it to document anything. It has a built-in search engine, generates table of contents and indexes, and because the files are just text files, you can check them into your favorite version control system and easily collaborate with and merge changes from other documentation contributors.

We will look at several popular open source software projects that are already using Sphinx, and show you how you can get started using Sphinx to document your software project.

Speaking experience

Speaker

  • Nate profile

    Nate Aune

    Appsembler

    Biography

    Nate Aune is CEO & Founder of Appsembler, a marketplace for open source web applications that you can deploy with 1-click. He’s deployed open source web applications to various cloud platforms such as Amazon AWS, Heroku, Dotcloud, Redhat’s OpenShift and Google App Engine. Nate is the founder and organizer of the Boston Django User Group with 800 members, and he served for 3 years on the Plone Foundation board.

    Nate has presented at LinuxWorld, Grassroots Use of Technology, Non-profit Software Developer Summit, EuroPython, PyCon and PyConBrasil. Read Nate’s blog at http://appsembler.com/blog and follow @natea on Twitter.

    Sessions