PyDoc Strings >>> def foo(a) :... "This the Foo function"... return str(a+1)... >>> help(foo) or from command line, pydoc module.foo

PyDoc Strings Pros: Builtin to Python Available from both Python CLI and shell Works with any Python object Cons: Doesn't support links or hyperlinks No standard for arguments or return types Resulting docs lack narrative or “big picture”

EPyDoc Enhanced PyDoc Strings, example: >>> def foo(a) :... '''This the Foo a : an a : number to L{bar}... '''... return str(a+1)

EPyDoc Pros: Added arguments, return values, links, etc Widespread usage, developers used to it “Backwards Compatible” with PyDoc Strings Cons: EPyDoc formatting not processed by help() HTML templates not using standard format Docs still lack narrative or “big picture”

Docutils Introduced ReStructured Text (ReST): Foo === Some text about the Foo function, `a link to URL `_ and **bold typeface**. Another paragraph, etc.

Docutils Pros: Full narrative documentation Robust, extensible markup Used for much more than just Python docs Cons: Only narrative, not tied into Python objects

Sphinx Extends ReStructured Text (ReST) for PyDoc: Foo === Some text about the :func:'Foo function ', `a link to URL `_ and **bold typeface**.

Sphinx Pros: PyDocs with ReST formatting in strings Narrative documentation including PyDocs Uses Django (Jinja) templates by default Most of the Python community is adopting Cons: EPyDoc (etc) markup not supported New project, not widely integrated yet