"Pycco" is a Python port of Docco: the original quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code. Comments are passed through Markdown and SmartyPants, while code is passed through Pygments for syntax highlighting. This page is the result of running Pycco against its own source file.

If you install Pycco, you can run it from the command-line:

pycco src/*.py

This will generate linked HTML documentation for the named source files, saving it into a docs folder by default.

The source for Pycco is available on GitHub, and released under the MIT license.

To install Pycco, simply

pip install pycco

Or, to install the latest source

git clone git:// cd pycco python install


Main Documentation Generation Functions


Generate the documentation for a source file by reading it in, splitting it up into comment/code sections, highlighting them for the appropriate language, and merging them into an HTML template.

def generate_documentation(source, outdir=None, preserve_paths=True):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
    fh = open(source, "r")
    sections = parse(source,
    highlight(source, sections, preserve_paths=preserve_paths, outdir=outdir)
    return generate_html(source, sections, preserve_paths=preserve_paths, outdir=outdir)

Given a string of source code, parse out each comment and the code that follows it, and create an individual section for it. Sections take the form:

{ "docs_text": ...,
"docs_html": ...,
"code_text": ...,
"code_html": ...,
"num":       ...
def parse(source, code):
    lines = code.split("\n")
    sections = []
    language = get_language(source)
    has_code = docs_text = code_text = ""

    if lines[0].startswith("#!"):

    if language["name"] == "python":
        for linenum, line in enumerate(lines[:2]):
            if'coding[:=]\s*([-\w.]+)', lines[linenum]):
    def save(docs, code):
        if docs or code:
                "docs_text": docs,
                "code_text": code

Setup the variables to get ready to check for multiline comments

    preformatted = multi_line = False
    last_scope = 0
    multi_line_delimiters = [language.get("multistart"), language.get("multiend")]

    for line in lines:

Only go into multiline comments section when one of the delimiters is found to be at the start of a line

        if all(multi_line_delimiters) and any([line.lstrip().startswith(delim) for delim in multi_line_delimiters]):
            if not multi_line:
                multi_line = True

                multi_line = False
            if (multi_line
               and line.strip().endswith(language.get("multiend"))
               and len(line.strip()) > len(language.get("multiend"))):
                multi_line = False

Get rid of the delimiters so that they aren't in the final docs

            line = re.sub(re.escape(language["multistart"]),'',line)
            line = re.sub(re.escape(language["multiend"]),'',line)
            docs_text += line.strip() + '\n'

            if has_code and docs_text.strip():
                save(docs_text, code_text[:-1])
                code_text = code_text.split('\n')[-1]
                last_scope = 0
                has_code = docs_text = ''

        elif multi_line:
            line_striped = line.rstrip()
            current_scope = line_striped.count("    ")

This section will parse if the line is indented at least four places, and if so know to have the final text treat it as a preformatted text block.

            if line_striped.startswith("    ") and last_scope:
                if current_scope > last_scope and not preformatted:
                    preformatted = True
                    docs_text += "<pre>"

                if preformatted:
                    preformatted = False
                    docs_text += "</pre>"

Keep a tracker var to see if the scope increases, that way later the code can decided if a section is indented more than 4 spaces from the leading code.

            last_scope = current_scope if current_scope > last_scope else last_scope
            docs_text += line.strip() + '\n'

        elif re.match(language["comment_matcher"], line):
            if has_code:
                save(docs_text, code_text)
                has_code = docs_text = code_text = ''
            docs_text += re.sub(language["comment_matcher"], "", line) + "\n"

            if code_text and any([line.lstrip().startswith(x) for x in ['class ', 'def ', '@']]):
                if not code_text.lstrip().startswith("@"):
                    save(docs_text, code_text)
                    code_text = has_code = docs_text = ''

            has_code = True
            code_text += line + '\n'

    save(docs_text, code_text)

    return sections

Preprocessing the comments


Add cross-references before having the text processed by markdown. It's possible to reference another file, like this : [[]] which renders You can also reference a specific section of another file, like this: [[]] which renders as Sections have to be manually declared; they are written on a single line, and surrounded by equals signs: === like this ===

def preprocess(comment, section_nr, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
    def sanitize_section_name(name):
        return "-".join(name.lower().strip().split(" "))
    def replace_crossref(match):

Check if the match contains an anchor

        if '#' in
            name, anchor ='#')
            return " [%s](%s#%s)" % (name,

            return " [%s](%s)" % (,
    def replace_section_name(match):
        return '%(lvl)s <span id="%(id)s" href="%(id)s">%(name)s</span>' % {
            "lvl"  : re.sub('=', '#',,
            "id"   : sanitize_section_name(,
            "name" :

    comment = re.sub('^([=]+)([^=]+)[=]*\s*$', replace_section_name, comment)
    comment = re.sub('[^`]\[\[(.+)\]\]', replace_crossref, comment)

    return comment

Highlighting the source code


Highlights a single chunk of code using the Pygments module, and runs the text of its corresponding comment through Markdown.

We process the entire file in a single call to Pygments by inserting little marker comments between each section and then splitting the result string wherever our markers occur.

def highlight(source, sections, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
    language = get_language(source)

    output = pygments.highlight(language["divider_text"].join(section["code_text"].rstrip() for section in sections),

    output = output.replace(highlight_start, "").replace(highlight_end, "")
    fragments = re.split(language["divider_html"], output)
    for i, section in enumerate(sections):
        section["code_html"] = highlight_start + shift(fragments, "") + highlight_end
            docs_text = unicode(section["docs_text"])
        except UnicodeError:
            docs_text = unicode(section["docs_text"].decode('utf-8'))
        section["docs_html"] = markdown(preprocess(docs_text,
        section["num"] = i

HTML Code generation


Once all of the code is finished highlighting, we can generate the HTML file and write out the documentation. Pass the completed sections into the template found in resources/pycco.html.

Pystache will attempt to recursively render context variables, so we must replace any occurences of {{, which is valid in some languages, with a "unique enough" identifier before rendering, and then post-process the rendered template and change the identifier back to {{.

def generate_html(source, sections, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument")
    title = path.basename(source)
    dest = destination(source, preserve_paths=preserve_paths, outdir=outdir)
    csspath = path.relpath(path.join(outdir, "pycco.css"), path.split(dest)[0])

    for sect in sections:
        sect["code_html"] = re.sub(r"\{\{", r"{{", sect["code_html"])

    rendered = pycco_template({
        "title"       : title,
        "stylesheet"  : csspath,
        "sections"    : sections,
        "source"      : source,
        "path"        : path,
        "destination" : destination

    return re.sub(r"{{", "{{", rendered).encode("utf-8")

Helpers & Setup


This module contains all of our static resources.

import pycco_resources

Import our external dependencies.

import optparse
import os
import pygments
import pystache
import re
import sys
import time
from markdown import markdown
from os import path
from pygments import lexers, formatters

A list of the languages that Pycco supports, mapping the file extension to the name of the Pygments lexer and the symbol that indicates a comment. To add another language to Pycco's repertoire, add it here.

languages = {
    ".coffee": { "name": "coffee-script", "symbol": "#" },

    ".pl":  { "name": "perl", "symbol": "#" },

    ".sql": { "name": "sql", "symbol": "--" },

    ".c":   { "name": "c", "symbol": "//"},

    ".cpp": { "name": "cpp", "symbol": "//"},

    ".js": { "name": "javascript", "symbol": "//",
        "multistart": "/*", "multiend": "*/"},

    ".rb": { "name": "ruby", "symbol": "#",
        "multistart": "=begin", "multiend": "=end"},

    ".py": { "name": "python", "symbol": "#",
        "multistart": '"""', "multiend": '"""' },

    ".scm": { "name": "scheme", "symbol": ";;",
        "multistart": "#|", "multiend": "|#"},

    ".lua": { "name": "lua", "symbol": "--",
        "multistart": "--[[", "multiend": "--]]"},

    ".erl": { "name": "erlang", "symbol": "%%" },

Build out the appropriate matchers and delimiters for each language.

for ext, l in languages.items():

Does the line begin with a comment?

    l["comment_matcher"] = re.compile(r"^\s*" + l["symbol"] + "\s?")

The dividing token we feed into Pygments, to delimit the boundaries between sections.

    l["divider_text"] = "\n" + l["symbol"] + "DIVIDER\n"

The mirror of divider_text that we expect Pygments to return. We can split on this to recover the original sections.

    l["divider_html"] = re.compile(r'\n*<span class="c[1]?">' + l["symbol"] + 'DIVIDER</span>\n*')

Get the Pygments Lexer for this language.

    l["lexer"] = lexers.get_lexer_by_name(l["name"])

Get the current language we're documenting, based on the extension.

def get_language(source):
        return languages[ source[source.rindex("."):] ]
    except ValueError:
        source = open(source, "r")
        code =
        lang = lexers.guess_lexer(code).name.lower()
        for l in languages.values():
            if l["name"] == lang:
                return l
            raise ValueError("Can't figure out the language!")

Compute the destination HTML path for an input source file path. If the source is lib/, the HTML will be at docs/example.html

def destination(filepath, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
        name = filepath.replace(filepath[ filepath.rindex("."): ], "")
    except ValueError:
        name = filepath
    if not preserve_paths:
        name = path.basename(name)
    return path.join(outdir, "%s.html" % name)

Shift items off the front of the list until it is empty, then return default.

def shift(list, default):
        return list.pop(0)
    except IndexError:
        return default

Ensure that the destination directory exists.

def ensure_directory(directory):
    if not os.path.isdir(directory):
def template(source):
    return lambda context: pystache.render(source, context)

Create the template that we will use to generate the Pycco HTML page.

pycco_template = template(pycco_resources.html)

The CSS styles we'd like to apply to the documentation.

pycco_styles = pycco_resources.css

The start of each Pygments highlight block.

highlight_start = "<div class=\"highlight\"><pre>"

The end of each Pygments highlight block.

highlight_end = "</pre></div>"

For each source file passed as argument, generate the documentation.

def process(sources, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")

Make a copy of sources given on the command line. main() needs the original list when monitoring for changed files.

    sources = sorted(sources)

Proceed to generating the documentation.

    if sources:
        css = open(path.join(outdir, "pycco.css"), "w")
        def next_file():
            s = sources.pop(0)
            dest = destination(s, preserve_paths=preserve_paths, outdir=outdir)

            except OSError:

            with open(destination(s, preserve_paths=preserve_paths, outdir=outdir), "w") as f:
                f.write(generate_documentation(s, preserve_paths=preserve_paths, outdir=outdir))

            print "pycco = %s -> %s" % (s, dest)

            if sources:

__all__ = ("process", "generate_documentation")

Monitor each source file and re-generate documentation on change.

def monitor(sources, opts):

The watchdog modules are imported in main() but we need to re-import here to bring them into the local namespace.

    import watchdog.observers

Watchdog operates on absolute paths, so map those to original paths as specified on the command line.

    absolute_sources = dict((os.path.abspath(source), source)
                            for source in sources)

A handler for recompiling files which triggered watchdog events

    class RegenerateHandler(

Regenerate documentation for a file which triggered an event

        def on_modified(self, event):

Re-generate documentation from a source file if it was listed on the command line. Watchdog monitors whole directories, so other files may cause notifications as well.

            if event.src_path in absolute_sources:

Set up an observer which monitors all directories for files given on the command line and notifies the handler defined above.

    event_handler = RegenerateHandler()
    observer = watchdog.observers.Observer()
    directories = set(os.path.split(source)[0] for source in sources)
    for directory in directories:
        observer.schedule(event_handler, path=directory)

Run the file change monitoring loop until the user hits Ctrl-C.

        while True:
    except KeyboardInterrupt:

Hook spot for the console script.

def main():
    parser = optparse.OptionParser()
    parser.add_option('-p', '--paths', action='store_true',
                      help='Preserve path structure of original files')

    parser.add_option('-d', '--directory', action='store', type='string',
                      dest='outdir', default='docs',
                      help='The output directory that the rendered files should go to.')

    parser.add_option('-w', '--watch', action='store_true',
                      help='Watch original files and re-generate documentation on changes')
    opts, sources = parser.parse_args()

    process(sources, outdir=opts.outdir, preserve_paths=opts.paths)

If the -w / --watch option was present, monitor the source directories for changes and re-generate documentation for source files whenever they are modified.

            import watchdog.observers
        except ImportError:
            sys.exit('The -w/--watch option requires the watchdog package.')

        monitor(sources, opts)

Run the script.

if __name__ == "__main__":