Creating Robust Documentation with Sphinx and Doctests
32
Creating Robust Documentation with Sphinx and Doctests Christopher Perkins PyWork November 2008
description
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. - PowerPoint PPT Presentation
Transcript of Creating Robust Documentation with Sphinx and Doctests
Title
Creating Robust Documentation with Sphinx and DoctestsChristopher PerkinsPyWorkNovember 2008What is Sphinx?
Auto Generated Docs
Developer Modifiable
But doesn't epydocs do that?
Yikes!Multiple Output Formats
LaTeXPDFHTML?reStructured Text
Developer Driven
Why do you need more than docstrings?Naratives
http://www.flickr.com/photos/josephhoetzl/2537201140/Tutorialshttp://farm4.static.flickr.com/3258/2725759719_c49318962e.jpg?v=0
Integrate
http://www.flickr.com/photos/happymonkey/2325420169/Restructured Text3Paragraphs in ReST I am a paragraph.
Hey! Look down here, another paragraph. Notice the line between me and my brother above.ListsI am the first item in the listI am part of an inner listI am also in the inner listI make this look easy.
Roman Numerals also work.Makes me look like Im a college thesis or something.HeadingsChapter 1 Title===============
Section 1.1 Title-----------------
Subsection 1.1.1 Title~~~~~~~~~~~~~~~~~~~~~~
Section 1.2 Title----------------
* The underline has to be the length of the textRestructured 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.LinksPython_ is `my favoriteprogramming language`__.
.. _Python: http://www.python.org/
__ Python_
Images.. image:: images/ball1.gifReST DirectivesLooks like: .. directive_name: : directive dataSphinx defines a number of directives.Provide your own directives with Sphinx extensions.First Demo
So? What else?Searchable
http://www.flickr.com/photos/peteashton/22934348/Customization
Pygments Syntax HighlightingActionScriptAssembly (various)BooBefungeBrainFuckC, C++C#Common LispDDelphiDylanErlangHaskell (incl. Literate Haskell)JavaJavaScriptLuaMiniDMooCodeMuPadOCamlPHPPerlPython (incl. console sessions and tracebacks)RedcodeRuby (incl. irb sessions)SchemeVisual Basic.NET and more!Testing Integration
Courtesy: XKCDDid you say Doctests?Test Discovery
(using Nose)Doctest Demo Here
In Summary.Documentation is important.Documentation should be correct.Not enough docs in OSS.If it's good enough for Guido...ReferencesTutorial: pythontutorials.googlecode.comMe: www.percious.comVideo Presentation: search sphinx at www.showmedo.comSphinx: sphinx.pocoo.org XKCD: http://blag.xkcd.com/
