Debugging helper for Sphinx

interactive-builder.py

# -*- coding: utf-8 -*-
"""
    sphinx.builders.interactive
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Drop to an interactive shell for debugging.

    :copyright: Copyright 2010 by the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
"""

import code
import pdb
import sys

import sphinx
from sphinx.builders import Builder

class InteractiveBuilder(Builder):
    """
    Drops build process to a debugger.
    """
    name = 'debug'

    def _drop(self, stage, **addlocal):
        if stage in self.stages:
            self.info()
            if self.use_pdb:
                pdb.set_trace()
            else:
                local = dict(builder=self, app=self.app, env=self.env, stages=self.stages)
                local.update(addlocal)
                banner = 'Python %s\nSphinx %s building %s (%s stage)' % (
                    sys.version, sphinx.__version__, self.config.project, stage)
                try:
                    code.interact(banner, local=local)
                except SystemExit:
                    pass

    def get_target_uri(self, docname, typ=None):
        return docname

    def get_outdated_docs(self):
        return 'debugging'

    def init(self):
        stages = self.config.debug_stages
        self.use_pdb = self.config.debug_pdb
        if isinstance(stages, basestring):
            stages = stages.split(":")
        self.stages = stages
        for stage in stages:
            if stage.startswith('emit-'):
                self.app.connect(stage[5:],
                    lambda app, *args:self._drop(stage, app=app, args=args))
        self._drop('init')

    def prepare_writing(self, docnames):
        self._drop('prepare', docnames=docnames)

    def write_doc(self, docname, doctree):
        self._drop('write-%s' % docname, doctree=doctree)

    def finish(self):
        self._drop('finish')