340 likes | 484 Views
Creating Robust Documentation with Sphinx and Doctests. Christopher Perkins PyWork November 2008. What is Sphinx?. Auto Generated Docs. Developer Modifiable. But doesn't epydocs do that?. Yikes!. Multiple Output Formats. LaTeX. PDF. HTML?. reStructured Text. Developer Driven.
E N D
Creating Robust Documentation with Sphinx and Doctests Christopher Perkins PyWork November 2008
Multiple Output Formats LaTeX PDF HTML?
Naratives http://www.flickr.com/photos/josephhoetzl/2537201140/
Tutorials http://farm4.static.flickr.com/3258/2725759719_c49318962e.jpg?v=0
Integrate http://www.flickr.com/photos/happymonkey/2325420169/
Paragraphs in ReST I am a paragraph. Hey! Look down here, another paragraph. Notice the line between me and my brother above.
Lists • I am the first item in the list • I am part of an inner list • I am also in the inner list • I make this look easy. • Roman Numerals also work. • Makes me look like I’m a college thesis or something.
Headings Chapter 1 Title =============== Section 1.1 Title ----------------- Subsection 1.1.1 Title ~~~~~~~~~~~~~~~~~~~~~~ Section 1.2 Title ---------------- * The underline has to be the length of the text…
Restructured Text Tables +------------+------------+-----------+ | Header 1 | Header 2 | Header 3 | +============+============+===========+ | body row 1 | column 2 | column 3 | +------------+------------+-----------+ | body row 2 | Cells may span columns.| +------------+------------+-----------+ | body row 3 | Cells may | - Cells | +------------+ span rows. | - contain | | body row 4 | | - blocks. | +------------+------------+-----------+
Etc. • Links Python_ is `my favorite programming language`__. .. _Python: http://www.python.org/ __ Python_ • Images .. image:: images/ball1.gif
ReST Directives • Looks like: .. directive_name: : directive data • Sphinx defines a number of directives. • Provide your own directives with Sphinx extensions.
Searchable http://www.flickr.com/photos/peteashton/22934348/
Pygments Syntax Highlighting • MuPad • OCaml • PHP • Perl • Python (incl. console sessions and tracebacks) • Redcode • Ruby (incl. irb sessions) • Scheme • Visual Basic.NET • and more! • Delphi • Dylan • Erlang • Haskell (incl. Literate Haskell) • Java • JavaScript • Lua • MiniD • MooCode • ActionScript • Assembly (various) • Boo • Befunge • BrainFuck • C, C++ • C# • Common Lisp • D
Testing Integration Courtesy: XKCD
Test Discovery (using Nose)
In Summary. • Documentation is important. • Documentation should be correct. • Not enough docs in OSS. • If it's good enough for Guido...
References • Tutorial: pythontutorials.googlecode.com • Me: www.percious.com • Video Presentation: search sphinx at www.showmedo.com • Sphinx: sphinx.pocoo.org • XKCD: http://blag.xkcd.com/