Extract SNAKES docstrings and generate API documentation from them in Markdown format (one file for each Python file). This is both a Python module and a command-line tool:

$ python -m snakes.utils.apidoc
[error] Usage: python -m snakes.utils.apidoc TARGET [EXCLUDE...]
        TARGET   target directory to write files
        EXCLUDE  pattern to exclude modules (not file names)
$ python -m snakes.utils.apidoc api snakes.lang.*
[info] snakes -> 'api/index.md'

With respect to existing API extractors, this one takes into account the structure of SNAKES, in particular, documentation for plugins is correctly searched within functions extend and rendered accordingly. Moreover, apidoc considers all the strings within modules or classes as docstrings, which is particularly useful to document modules.

There is no real user manual for apidoc, in particular about its syntax and usage, the best source of information is probably to look at SNAKES source code. However, let's note a few points:

Note: in the example above we do not build doc for the sub-modules of snakes.lang because some of them are programmed for distinct versions of Python with incompatible syntaxes. So apidoc will fail for sure on one or another of these modules. Fortunately, most of the documentation for snakes.lang is in the package itself.
Note: for better rendering, apidoc uses Python Markdown, however, it will handle situations when it is not installed
Warning: apidoc has been tested only with SNAKES source, I guess it should work in other cases but this may required some work

Class DocExtract

class DocExtract (object) :

The class that extracts documentation and renders it

Method DocExtract.__init__

def __init__ (self, inpath, outpath, exclude=[],
              inputenc="utf-8", outputenc="utf-8") : ...
Call API

Method DocExtract.md

def md (self, text, inline=True) :

Return the Markdow rendering of text, include <p> if inline is False. If Python Markdown module is not installed, text is returned unchanged.

Call API

Method DocExtract.openout

def openout (self, path) :

Open in self.out the output file where the conversion of input file path will be rendered. If self.out is already opened, it is first closed.

Return a Boolean indicating if path should be ignored, in which case the output file is not opened. This occurs either if path correspond to a module that has been excluded or if the output file exists and is newer than the input file.

Note: package files called __init__.py are converted to files called index.md so that when converted to HTML, this will yield a file called index.html
Call API

Method DocExtract.write

def write (self, text) :

Write text to output file

Call API

Method DocExtract.newline

def newline (self) :

Write a blank line to output file, never more than one blank line is written so there is no need to be carefull about how many successive times newline is called (which would be complicated when multiple calls are made from different locations).

Method DocExtract.writeline

def writeline (self, text="") :

Write a line of text to output file, ensuring there is a end-of-line character at the end (and removing those that may exist in text).

Call API

Method DocExtract.writetext

def writetext (self, text, **args) :

Write some text to output file, with line wrapping.

Call API

Method DocExtract.writelist

def writelist (self, text, bullet="  * ", **args) :

Write one list item to output file, wrapping the text properly.

Call API

Method DocExtract.process

def process (self) :

Main method that process input directory and write converted files to output directory.

Each input file is parsed using snakes.lang.python to an AST that is then traversed for processing.

Method DocExtract.directive

def directive (self, node) :

Return directives (skip, stop, include) for this node, or None

Call API

Method DocExtract.children

def children (self, node) :

Iterates over the children of node

Call API

Method DocExtract.visit

def visit (self, node) :

Generic visit of a node that actually dispatch to the appropriate method visit_...

Method DocExtract.visit_module

def visit_module (self, node) :

Visit a node that is a module

Method DocExtract.visit_plugin

def visit_plugin (self, node) :

Visit a node that is a plugin

Method DocExtract.visit_ClassDef

def visit_ClassDef (self, node) :

Visit a node that is a class definition

Method DocExtract.visit_FunctionDef

def visit_FunctionDef (self, node) :

Visit a node that is a function definition

Method DocExtract.visit_Expr

def visit_Expr (self, node) :

Visit a node that is an expression

Method DocExtract.visit_Str

def visit_Str (self, node) :

Visit a node that is a string literal

Method DocExtract.write_module

def write_module (self) :

Write the documentation about a module (not its content), which is just a title. The module name is in self.module and there is also a Boolean self.package to indicate if this module is a actually package.

Method DocExtract.write_plugin

def write_plugin (self) :

Write the documentation about function extend in a plugin (not its content), which is just a title

Method DocExtract.write_function

def write_function (self, node) :

Write the documentation about a function or method (which can be differentiated by looking if self.classname is not None)

Method DocExtract.write_class

def write_class (self, node) :

Write the documentation about a class

Method DocExtract.write_def

def write_def (self, node) :

Write the documentation about a function or method definition (parameters, decorators, etc.)

Method DocExtract.write_doc

def write_doc (self, doc) :

Write the content of a docstring that is parsed to extract doctests, Epydoc fields and plain text

Method DocExtract.write_epydoc

def write_epydoc (self, doc) :

Write a block of epydoc fields

Method DocExtract.write_include

def write_include (self, name, lang="python", first=1, last=-1) :

Write a block of source code included through directive apidoc include ...

Function main

def main (finder, args, source=None) :

Main function of apidoc. Source directory may be given explicitly, otherwise it is computed as follows:

import snakes
source = os.path.dirname(snakes.__file__)

So it is important to set PYTHONPATH or sys.path if you want to use a non-standard location for SNAKES.

Call API