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:

• most Epydoc fields are supported: @param, @type, @note, ...
• directive # apidoc skip allow not to include the next object in the generated documentation
• directive # apidoc stop allow to stop the processing of current object (module or class)
• directive # apidoc include 'filename' lang='language' allow to include the content of a file as a block of source code in the specified language
• when statement pass is found in a doctest, the rest of the doctest is skipped, this is useful when this doctest is for test purpose only but does not provide useful documentation in itself
• the syntax is that supported by Markdown Python module, with no extensions other that Epydoc fields
• apidoc is intended to be simple and so does not support many options nor customisation, however, it is quite flexible already by the way it handles documentation

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

• str inpath: directory where the source code is searched for
• str outpath: directory where the documentation is generated
• list exclude: a list of glob patterns to exclude modules (not file names, but Python modules names)
• str inputenc: encoding of input files
• str outputenc: encoding of output files

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

• str text: the text to be rendered
• bool inline: True if this text is part of a larger paragraph, False if this is a paragraph by itself
• return str: HTML text

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.

Call API

• str path: input file to be converted
• return bool: True is output file is open and ready, False if input file should be skipped

Method DocExtract.write

def write (self, text) :

Write text to output file

Call API

• str text: the text to write

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

• str text: the text to write

Method DocExtract.writetext

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

Write some text to output file, with line wrapping.

Call API

• str text: the text to write
• object args: additional arguments to textwrap.wrap

Method DocExtract.writelist

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

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

Call API

• str text: the text within the item
• str bullet: list marker
• object args: additional arguments to textwrap.wrap

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

• AST node: an AST node

Method DocExtract.children

def children (self, node) :

Iterates over the children of node

Call API

• AST node: an AST node
• return generator: all the children but the skipped ones, until the end of stop directive is found

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

• class finder: DocExtract or a subclass of it to perform the processing
• list args: command line arguments
• str source: the source directory for the code to be documented, or None to extract documentation from SNAKES