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 SmartyPants1, 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

  1. Three extensions to Markdown are available:

    1. SmartyPants
    2. Fenced code blocks
    3. Footnotes

from __future__ import absolute_import, print_function

Import our external dependencies.

import argparse
import os
import re
import sys
import time
from os import path

import pygments
from pygments import formatters, lexers

from markdown import markdown
from pycco.generate_index import generate_index
from pycco.languages import supported_languages
from pycco_resources import css as pycco_css

This module contains all of our static resources.

from pycco_resources import pycco_template

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,
                           language=None, encoding="utf8"):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
    code = open(source, "rb").read().decode(encoding)
    return _generate_documentation(source, code, outdir, preserve_paths, language)

Helper function to allow documentation generation without file handling.

def _generate_documentation(file_path, code, outdir, preserve_paths, language):
    language = get_language(file_path, code, language_name=language)
    sections = parse(code, language)
    highlight(sections, language, preserve_paths=preserve_paths, outdir=outdir)
    return generate_html(file_path, 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(code, language):
    lines = code.split("\n")
    sections = []
    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

    multi_line = False
    multi_string = False
    multistart, multiend = language.get("multistart"), language.get("multiend")
    comment_matcher = language['comment_matcher']

    for line in lines:
        process_as_code = False

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

        if multistart and multiend \
           and any(line.lstrip().startswith(delim) or line.rstrip().endswith(delim)
                   for delim in (multistart, multiend)):
            multi_line = not multi_line

            if multi_line \
               and line.strip().endswith(multiend) \
               and len(line.strip()) > len(multiend):
                multi_line = False

            if not line.strip().startswith(multistart) and not multi_line \
               or multi_string:

                process_as_code = True

                if multi_string:
                    multi_line = False
                    multi_string = False
                    multi_string = True


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

                line = line.replace(multistart, '')
                line = line.replace(multiend, '')
                docs_text += line.strip() + '\n'
                indent_level = re.match(r"\s*", line).group(0)

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

        elif multi_line:

Remove leading spaces

            if re.match(r' {{{:d}}}'.format(len(indent_level)), line):
                docs_text += line[len(indent_level):] + '\n'
                docs_text += line + '\n'

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

            process_as_code = True

        if process_as_code:
            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, 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 " [{}]({}#{})".format(name,

            return " [{}]({})".format(,

Replace equals-sign-formatted section names with anchor links.

    def replace_section_name(match):
        return '{lvl} <span id="{id}" href="{id}">{name}</span>'.format(
            lvl=re.sub('=', '#',,

    comment = re.sub(r'^([=]+)([^=]+)[=]*\s*$', replace_section_name, comment)
    comment = re.sub(r'(?<!`)\[\[(.+?)\]\]', 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(sections, language, preserve_paths=True, outdir=None):
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")

    divider_text = language["divider_text"]
    lexer = language["lexer"]
    divider_html = language["divider_html"]

    joined_text = divider_text.join(
        section["code_text"].rstrip() for section in sections
    html_formatter = formatters.get_formatter_by_name("html")

    output = pygments.highlight(
        joined_text, lexer, html_formatter
        highlight_start, ""
        highlight_end, ""
    fragments = re.split(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'))
        except NameError:
            docs_text = section['docs_text']
        section["docs_html"] = markdown(
        section["num"] = i

    return sections

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,

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

Helpers & Setup


Build out the appropriate matchers and delimiters for each language.

def compile_language(l):
    language_name = l["name"]
    comment_symbol = l["comment_symbol"]

Does the line begin with a comment?

    l["comment_matcher"] = re.compile(r"^\s*{}\s?".format(comment_symbol))

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

    l["divider_text"] = "\n{}DIVIDER\n".format(comment_symbol)

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]?">{}DIVIDER</span>\n*'.format(comment_symbol)

Get the Pygments Lexer for this language.

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

for entry in supported_languages.values():

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

def get_language(source, code, language_name=None):
    if language_name is not None:
        for entry in supported_languages.values():
            if entry["name"] == language_name:
                return entry
            raise ValueError("Unknown forced language: {}".format(language_name))

    if source:
        m = re.match(r'.*(\..+)', os.path.basename(source))
        if m and in supported_languages:
            return supported_languages[]

        language_name = lexers.guess_lexer(code).name.lower()
        for entry in supported_languages.values():
            if entry["name"] == language_name:
                return entry
            raise ValueError()
    except ValueError:

If pygments can’t find any lexers, it will raise its own subclass of ValueError. We will catch it and raise ours for consistency.

        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):
    dirname, filename = path.split(filepath)
    if not outdir:
        raise TypeError("Missing the required 'outdir' keyword argument.")
        name = re.sub(r"\.[^.]*$", "", filename)
    except ValueError:
        name = filename
    if preserve_paths:
        name = path.join(dirname, name)
    dest = path.join(outdir, u"{}.html".format(name))

If join is passed an absolute path, it will ignore any earlier path elements. We will force outdir to the beginning of the path to avoid writing outside our destination.

    if not dest.startswith(outdir):
        dest = outdir + os.sep + dest
    return dest

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
def remove_control_chars(s):

Sanitization regexp copied from

    from pycco.compat import pycco_unichr
    control_chars = ''.join(
        map(pycco_unichr, list(range(0, 32)) + list(range(127, 160))))
    control_char_re = re.compile(u'[{}]'.format(re.escape(control_chars)))
    return control_char_re.sub('', s)

Sanitize directory string and ensure that the destination directory exists.

def ensure_directory(directory):
    directory = remove_control_chars(directory)
    if not os.path.isdir(directory):

    return directory

The start of each Pygments highlight block.

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

The end of each Pygments highlight block.

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

This function will iterate through the list of sources and if a directory is encountered it will walk the tree for any files.

def _flatten_sources(sources):
    _sources = []

    for source in sources:
        if os.path.isdir(source):
            for dirpath, _, filenames in os.walk(source):
                _sources.extend([os.path.join(dirpath, f) for f in filenames])

    return _sources

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

def process(sources, preserve_paths=True, outdir=None, language=None,
            encoding="utf8", index=False, skip=False):
    if not outdir:
        raise TypeError("Missing the required 'directory' keyword argument.")

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

    sources = sorted(_flatten_sources(sources))

Proceed to generating the documentation.

    if sources:
        outdir = ensure_directory(outdir)
        css = open(path.join(outdir, "pycco.css"), "wb")

        generated_files = []
        def next_file():
            s = sources.pop(0)
            dest = destination(s, preserve_paths=preserve_paths, outdir=outdir)

            except OSError:

                with open(dest, "wb") as f:
                    f.write(generate_documentation(s, preserve_paths=preserve_paths,

                print("pycco: {} -> {}".format(s, dest))
            except (ValueError, UnicodeDecodeError) as e:
                if skip:
                    print("pycco [FAILURE]: {}, {}".format(s, e))

            if sources:

        if index:
            with open(path.join(outdir, "index.html"), "wb") as f:
                f.write(generate_index(generated_files, outdir))

__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 = argparse.ArgumentParser()
    parser.add_argument('-p', '--paths', action='store_true',
                      help='Preserve path structure of original files')

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

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

    parser.add_argument('-l', '--force-language', action='store', type=str,
                      dest='language', default=None,
                      help='Force the language for the given files')

    parser.add_argument('-i', '--generate_index', action='store_true',
                      help='Generate an index.html document with sitemap content')

    parser.add_argument('-s', '--skip-bad-files', '-e', '--ignore-errors',
                      help='Continue processing after hitting a bad file')

    parser.add_argument('sources', nargs='*')

    args = parser.parse_args()
    if args.outdir == '':
        outdir = '.'
        outdir = args.outdir

    process(args.sources, outdir=outdir, preserve_paths=args.paths,
            language=args.language, index=args.generate_index,

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  # noqa
        except ImportError:
            sys.exit('The -w/--watch option requires the watchdog package.')

        monitor(args.sources, args)

Run the script.

if __name__ == "__main__":