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

3. 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”

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

5. 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”

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

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

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

9. 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