docdoc.py

Generates Python documentation in Markdown using Python docstrings.

This module is an early experimentation to see how feasible it is to only use docstrings and class/function definitions as the source for documentation. Since the idea of Python is self-documenting, this should suffice for most small projects.

Markdown is chosen becuase the author likes it. Thanks, John Gruber.

This module was created quickly, so many features are missing. If you would like to see something implemented, please create an issue.

Installation

Get the module from Github (cheeseshop package coming soon):

$ git clone git://github.com/Spaxe/docdoc.git

Add the module's path to ypur $PYTHONPATH.

Usage (as a module)

>>> from docdoc import docdoc
>>> print docodc(<filepath>)

Usage (from terminal)

$ ./docdoc.py <filepath>

DocumentationGenerator (ast.NodeVisitor)

Extracts docstrings from a Python AST node.

This class should be used like an ast.NodeVisitor; see main for an example. Once the parsing is done, the caller can use format_doc() to retrieve the final markdown for further use.

init (self)

Constructor.

add_doc (self, name, args, documentation, level=1, decorators=None)

Records a documentation item.

format_doc (self)

Return the final markdown string with the documentation items.

visit_Module (self, module_node)

Automatically called when visiting a Module.

visit_ClassDef (self, class_node)

Automatically called when visiting a ClassDef.

parse_ClassDef (self, node, level=2)

Extracts documentation from a ClassDef.

parse_FunctionDef (self, node, level=2)

Extracts documentation from a FunctionDef.

parse_Literals (self, node)

Extracts Python literals from a value/expression node.

docdoc (filepath)

Parses the Python source file. Returns documentation in markdown.