Sphinx - the ultimate tool for documenting your software project
*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.
Tags
python, documentation, docs, sphinx, manual
Speaking experience
Speaker
-
Nate Aune
Jazkarta- Website: http://www.jazkarta.com/
- Blog: http://blog.jazkarta.com/
- Twitter: natea
- Favorites: View Nate's favorites
Biography
Nate Aune is founder and director of Jazkarta, a Boston-based consulting firm specializing in open source web solutions for non-profits and universities. Nate spearheaded the Plone4Artists project and regularly leads developer sprints to improve the multimedia and calendaring capabilities of Plone.
He organizes the Plone and Django user groups in Boston and is serving his third term 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://blog.jazkarta.com and follow @natea on Twitter.
Sessions
-
- Title: Sphinx - the ultimate tool for documenting your software project
- Track: Cooking
- Room: Fremont
- Time: 2:30 – 3:15pm
-
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.
- Speakers: Nate Aune