Convert builtin directives to classes. Refactor desc_directive so that it is easier to subclass.

sphinx/application.py

@@ -57,8 +57,7 @@ import sphinx
 from sphinx.roles import xfileref_role, innernodetypes
 from sphinx.config import Config
 from sphinx.builders import BUILTIN_BUILDERS
-from sphinx.directives import desc_directive, target_directive, \
+from sphinx.directives import GenericDesc, Target, additional_xref_types
-     additional_xref_types
 from sphinx.environment import SphinxStandaloneReader
 from sphinx.util.compat import Directive, directive_dwim
 from sphinx.util.console import bold
@@ -314,7 +313,7 @@ class Sphinx(object):
                              parse_node=None, ref_nodeclass=None):
         additional_xref_types[directivename] = (rolename, indextemplate,
                                                 parse_node)
-        directives.register_directive(directivename, desc_directive)
+        directives.register_directive(directivename, GenericDesc)
         roles.register_canonical_role(rolename, xfileref_role)
         if ref_nodeclass is not None:
             innernodetypes[rolename] = ref_nodeclass
@@ -322,7 +321,7 @@ class Sphinx(object):
     def add_crossref_type(self, directivename, rolename, indextemplate='',
                           ref_nodeclass=None):
         additional_xref_types[directivename] = (rolename, indextemplate, None)
-        directives.register_directive(directivename, target_directive)
+        directives.register_directive(directivename, Target)
         roles.register_canonical_role(rolename, xfileref_role)
         if ref_nodeclass is not None:
             innernodetypes[rolename] = ref_nodeclass

sphinx/directives/code.py

@@ -16,135 +16,159 @@ from docutils.parsers.rst import directives
 
 from sphinx import addnodes
 from sphinx.util import parselinenos
+from sphinx.util.compat import Directive
 
 
-# ------ highlight directive ---------------------------------------------------
+class Highlight(Directive):
+    """
+    Directive to set the highlighting language for code blocks, as well
+    as the threshold for line numbers.
+    """
 
-def highlightlang_directive(name, arguments, options, content, lineno,
+    has_content = False
-                            content_offset, block_text, state, state_machine):
+    required_arguments = 1
-    if 'linenothreshold' in options:
+    optional_arguments = 0
-        try:
+    final_argument_whitespace = False
-            linenothreshold = int(options['linenothreshold'])
+    option_spec = {
-        except Exception:
+        'linenothreshold': directives.unchanged,
-            linenothreshold = 10
+    }
-    else:
-        linenothreshold = sys.maxint
-    return [addnodes.highlightlang(lang=arguments[0].strip(),
-                                   linenothreshold=linenothreshold)]
 
-highlightlang_directive.content = 0
+    def run(self):
-highlightlang_directive.arguments = (1, 0, 0)
+        if 'linenothreshold' in self.options:
-highlightlang_directive.options = {'linenothreshold': directives.unchanged}
+            try:
-directives.register_directive('highlight', highlightlang_directive)
+                linenothreshold = int(self.options['linenothreshold'])
-# old name
+            except Exception:
-directives.register_directive('highlightlang', highlightlang_directive)
+                linenothreshold = 10
-
-
-# ------ code-block directive --------------------------------------------------
-
-def codeblock_directive(name, arguments, options, content, lineno,
-                        content_offset, block_text, state, state_machine):
-    code = u'\n'.join(content)
-    literal = nodes.literal_block(code, code)
-    literal['language'] = arguments[0]
-    literal['linenos'] = 'linenos' in options
-    return [literal]
-
-codeblock_directive.content = 1
-codeblock_directive.arguments = (1, 0, 0)
-codeblock_directive.options = {'linenos': directives.flag}
-directives.register_directive('code-block', codeblock_directive)
-directives.register_directive('sourcecode', codeblock_directive)
-
-
-# ------ literalinclude directive ----------------------------------------------
-
-def literalinclude_directive(name, arguments, options, content, lineno,
-                             content_offset, block_text, state, state_machine):
-    """Like .. include:: :literal:, but only warns if the include file is
-    not found."""
-    if not state.document.settings.file_insertion_enabled:
-        return [state.document.reporter.warning('File insertion disabled',
-                                                line=lineno)]
-    env = state.document.settings.env
-    rel_fn = arguments[0]
-    source_dir = path.dirname(path.abspath(state_machine.input_lines.source(
-        lineno - state_machine.input_offset - 1)))
-    fn = path.normpath(path.join(source_dir, rel_fn))
-
-    if 'pyobject' in options and 'lines' in options:
-        return [state.document.reporter.warning(
-            'Cannot use both "pyobject" and "lines" options', line=lineno)]
-
-    encoding = options.get('encoding', env.config.source_encoding)
-    try:
-        f = codecs.open(fn, 'rU', encoding)
-        lines = f.readlines()
-        f.close()
-    except (IOError, OSError):
-        return [state.document.reporter.warning(
-            'Include file %r not found or reading it failed' % arguments[0],
-            line=lineno)]
-    except UnicodeError:
-        return [state.document.reporter.warning(
-            'Encoding %r used for reading included file %r seems to '
-            'be wrong, try giving an :encoding: option' %
-            (encoding, arguments[0]))]
-
-    objectname = options.get('pyobject')
-    if objectname is not None:
-        from sphinx.pycode import ModuleAnalyzer
-        analyzer = ModuleAnalyzer.for_file(fn, '')
-        tags = analyzer.find_tags()
-        if objectname not in tags:
-            return [state.document.reporter.warning(
-                'Object named %r not found in include file %r' %
-                (objectname, arguments[0]), line=lineno)]
         else:
-            lines = lines[tags[objectname][1] - 1 : tags[objectname][2] - 1]
+            linenothreshold = sys.maxint
+        return [addnodes.highlightlang(lang=self.arguments[0].strip(),
+                                       linenothreshold=linenothreshold)]
 
-    linespec = options.get('lines')
+
-    if linespec is not None:
+class CodeBlock(Directive):
+    """
+    Directive for a code block with special highlighting or line numbering
+    settings.
+    """
+
+    has_content = True
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'linenos': directives.flag,
+    }
+
+    def run(self):
+        code = u'\n'.join(self.content)
+        literal = nodes.literal_block(code, code)
+        literal['language'] = self.arguments[0]
+        literal['linenos'] = 'linenos' in self.options
+        return [literal]
+
+
+class LiteralInclude(Directive):
+    """
+    Like ``.. include:: :literal:``, but only warns if the include file is
+    not found, and does not raise errors.  Also has several options for
+    selecting what to include.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'linenos': directives.flag,
+        'language': directives.unchanged_required,
+        'encoding': directives.encoding,
+        'pyobject': directives.unchanged_required,
+        'lines': directives.unchanged_required,
+        'start-after': directives.unchanged_required,
+        'end-before': directives.unchanged_required,
+    }
+
+    def run(self):
+        document = self.state.document
+        filename = self.arguments[0]
+        if not document.settings.file_insertion_enabled:
+            return [document.reporter.warning('File insertion disabled',
+                                              line=self.lineno)]
+        env = document.settings.env
+        rel_fn = filename
+        sourcename = self.state_machine.input_lines.source(
+            self.lineno - self.state_machine.input_offset - 1)
+        source_dir = path.dirname(path.abspath(sourcename))
+        fn = path.normpath(path.join(source_dir, rel_fn))
+
+        if 'pyobject' in self.options and 'lines' in self.options:
+            return [document.reporter.warning(
+                'Cannot use both "pyobject" and "lines" options',
+                line=self.lineno)]
+
+        encoding = self.options.get('encoding', env.config.source_encoding)
         try:
-            linelist = parselinenos(linespec, len(lines))
+            f = codecs.open(fn, 'rU', encoding)
-        except ValueError, err:
+            lines = f.readlines()
-            return [state.document.reporter.warning(str(err), line=lineno)]
+            f.close()
-        lines = [lines[i] for i in linelist]
+        except (IOError, OSError):
+            return [document.reporter.warning(
+                'Include file %r not found or reading it failed' % filename,
+                line=self.lineno)]
+        except UnicodeError:
+            return [document.reporter.warning(
+                'Encoding %r used for reading included file %r seems to '
+                'be wrong, try giving an :encoding: option' %
+                (encoding, filename))]
 
-    startafter = options.get('start-after')
+        objectname = self.options.get('pyobject')
-    endbefore = options.get('end-before')
+        if objectname is not None:
-    if startafter is not None or endbefore is not None:
+            from sphinx.pycode import ModuleAnalyzer
-        use = not startafter
+            analyzer = ModuleAnalyzer.for_file(fn, '')
-        res = []
+            tags = analyzer.find_tags()
-        for line in lines:
+            if objectname not in tags:
-            if not use and startafter in line:
+                return [document.reporter.warning(
-                use = True
+                    'Object named %r not found in include file %r' %
-            elif use and endbefore in line:
+                    (objectname, filename), line=self.lineno)]
-                use = False
+            else:
-                break
+                lines = lines[tags[objectname][1]-1 : tags[objectname][2]-1]
-            elif use:
-                res.append(line)
-        lines = res
 
-    text = ''.join(lines)
+        linespec = self.options.get('lines')
-    retnode = nodes.literal_block(text, text, source=fn)
+        if linespec is not None:
-    retnode.line = 1
+            try:
-    if options.get('language', ''):
+                linelist = parselinenos(linespec, len(lines))
-        retnode['language'] = options['language']
+            except ValueError, err:
-    if 'linenos' in options:
+                return [document.reporter.warning(str(err), line=self.lineno)]
-        retnode['linenos'] = True
+            lines = [lines[i] for i in linelist]
-    state.document.settings.env.note_dependency(rel_fn)
-    return [retnode]
 
-literalinclude_directive.options = {
+        startafter = self.options.get('start-after')
-    'linenos': directives.flag,
+        endbefore = self.options.get('end-before')
-    'language': directives.unchanged_required,
+        if startafter is not None or endbefore is not None:
-    'encoding': directives.encoding,
+            use = not startafter
-    'pyobject': directives.unchanged_required,
+            res = []
-    'lines': directives.unchanged_required,
+            for line in lines:
-    'start-after': directives.unchanged_required,
+                if not use and startafter in line:
-    'end-before': directives.unchanged_required,
+                    use = True
-}
+                elif use and endbefore in line:
-literalinclude_directive.content = 0
+                    use = False
-literalinclude_directive.arguments = (1, 0, 0)
+                    break
-directives.register_directive('literalinclude', literalinclude_directive)
+                elif use:
+                    res.append(line)
+            lines = res
+
+        text = ''.join(lines)
+        retnode = nodes.literal_block(text, text, source=fn)
+        retnode.line = 1
+        if self.options.get('language', ''):
+            retnode['language'] = self.options['language']
+        if 'linenos' in self.options:
+            retnode['linenos'] = True
+        document.settings.env.note_dependency(rel_fn)
+        return [retnode]
+
+
+directives.register_directive('highlight', Highlight)
+directives.register_directive('highlightlang', Highlight) # old name
+directives.register_directive('code-block', CodeBlock)
+directives.register_directive('sourcecode', CodeBlock)
+directives.register_directive('literalinclude', LiteralInclude)

sphinx/directives/other.py

@@ -15,266 +15,313 @@ from docutils.parsers.rst import directives
 from sphinx import addnodes
 from sphinx.locale import pairindextypes
 from sphinx.util import patfilter, ws_re, caption_ref_re, url_re, docname_join
-from sphinx.util.compat import make_admonition
+from sphinx.util.compat import Directive, make_admonition
 
 
-# ------ the TOC tree ----------------------------------------------------------
+class TocTree(Directive):
+    """
+    Directive to notify Sphinx about the hierarchical structure of the docs,
+    and to include a table-of-contents like tree in the current document.
+    """
 
-def toctree_directive(name, arguments, options, content, lineno,
+    has_content = True
-                      content_offset, block_text, state, state_machine):
+    required_arguments = 0
-    env = state.document.settings.env
+    optional_arguments = 0
-    suffix = env.config.source_suffix
+    final_argument_whitespace = False
-    glob = 'glob' in options
+    option_spec = {
+        'maxdepth': int,
+        'glob': directives.flag,
+        'hidden': directives.flag,
+    }
 
-    ret = []
+    def run(self):
-    # (title, ref) pairs, where ref may be a document, or an external link,
+        env = self.state.document.settings.env
-    # and title may be None if the document's title is to be used
+        suffix = env.config.source_suffix
-    entries = []
+        glob = 'glob' in self.options
-    includefiles = []
+
-    includetitles = {}
+        ret = []
-    all_docnames = env.found_docs.copy()
+        # (title, ref) pairs, where ref may be a document, or an external link,
-    # don't add the currently visited file in catch-all patterns
+        # and title may be None if the document's title is to be used
-    all_docnames.remove(env.docname)
+        entries = []
-    for entry in content:
+        includefiles = []
-        if not entry:
+        includetitles = {}
-            continue
+        all_docnames = env.found_docs.copy()
-        if not glob:
+        # don't add the currently visited file in catch-all patterns
-            # look for explicit titles and documents ("Some Title <document>").
+        all_docnames.remove(env.docname)
-            m = caption_ref_re.match(entry)
+        for entry in self.content:
-            if m:
+            if not entry:
-                ref = m.group(2)
+                continue
-                title = m.group(1)
+            if not glob:
-                docname = ref
+                # look for explicit titles ("Some Title <document>")
+                m = caption_ref_re.match(entry)
+                if m:
+                    ref = m.group(2)
+                    title = m.group(1)
+                    docname = ref
+                else:
+                    ref = docname = entry
+                    title = None
+                # remove suffixes (backwards compatibility)
+                if docname.endswith(suffix):
+                    docname = docname[:-len(suffix)]
+                # absolutize filenames
+                docname = docname_join(env.docname, docname)
+                if url_re.match(ref) or ref == 'self':
+                    entries.append((title, ref))
+                elif docname not in env.found_docs:
+                    ret.append(self.state.document.reporter.warning(
+                        'toctree references unknown document %r' % docname,
+                        line=self.lineno))
+                else:
+                    entries.append((title, docname))
+                    includefiles.append(docname)
             else:
-                ref = docname = entry
+                patname = docname_join(env.docname, entry)
-                title = None
+                docnames = sorted(patfilter(all_docnames, patname))
-            # remove suffixes (backwards compatibility)
+                for docname in docnames:
-            if docname.endswith(suffix):
+                    all_docnames.remove(docname) # don't include it again
-                docname = docname[:-len(suffix)]
+                    entries.append((None, docname))
-            # absolutize filenames
+                    includefiles.append(docname)
-            docname = docname_join(env.docname, docname)
+                if not docnames:
-            if url_re.match(ref) or ref == 'self':
+                    ret.append(self.state.document.reporter.warning(
-                entries.append((title, ref))
+                        'toctree glob pattern %r didn\'t match any documents'
-            elif docname not in env.found_docs:
+                        % entry, line=self.lineno))
-                ret.append(state.document.reporter.warning(
+        subnode = addnodes.toctree()
-                    'toctree references unknown document %r' % docname,
+        subnode['parent'] = env.docname
-                    line=lineno))
+        subnode['entries'] = entries
-            else:
+        subnode['includefiles'] = includefiles
-                entries.append((title, docname))
+        subnode['maxdepth'] = self.options.get('maxdepth', -1)
-                includefiles.append(docname)
+        subnode['glob'] = glob
-        else:
+        subnode['hidden'] = 'hidden' in self.options
-            patname = docname_join(env.docname, entry)
+        ret.append(subnode)
-            docnames = sorted(patfilter(all_docnames, patname))
+        return ret
-            for docname in docnames:
-                all_docnames.remove(docname) # don't include it again
-                entries.append((None, docname))
-                includefiles.append(docname)
-            if not docnames:
-                ret.append(state.document.reporter.warning(
-                    'toctree glob pattern %r didn\'t match any documents'
-                    % entry, line=lineno))
-    subnode = addnodes.toctree()
-    subnode['parent'] = env.docname
-    subnode['entries'] = entries
-    subnode['includefiles'] = includefiles
-    subnode['maxdepth'] = options.get('maxdepth', -1)
-    subnode['glob'] = glob
-    subnode['hidden'] = 'hidden' in options
-    ret.append(subnode)
-    return ret
-
-toctree_directive.content = 1
-toctree_directive.options = {'maxdepth': int, 'glob': directives.flag,
-                             'hidden': directives.flag}
-directives.register_directive('toctree', toctree_directive)
 
 
-# ------ section metadata ------------------------------------------------------
+class Module(Directive):
+    """
+    Directive to mark description of a new module.
+    """
 
-def module_directive(name, arguments, options, content, lineno,
+    has_content = False
-                     content_offset, block_text, state, state_machine):
+    required_arguments = 1
-    env = state.document.settings.env
+    optional_arguments = 0
-    modname = arguments[0].strip()
+    final_argument_whitespace = False
-    noindex = 'noindex' in options
+    option_spec = {
-    env.currmodule = modname
+        'platform': lambda x: x,
-    env.note_module(modname, options.get('synopsis', ''),
+        'synopsis': lambda x: x,
-                    options.get('platform', ''),
+        'noindex': directives.flag,
-                    'deprecated' in options)
+        'deprecated': directives.flag,
-    modulenode = addnodes.module()
+    }
-    modulenode['modname'] = modname
-    modulenode['synopsis'] = options.get('synopsis', '')
-    targetnode = nodes.target('', '', ids=['module-' + modname])
-    state.document.note_explicit_target(targetnode)
-    ret = [modulenode, targetnode]
-    if 'platform' in options:
-        modulenode['platform'] = options['platform']
-        node = nodes.paragraph()
-        node += nodes.emphasis('', _('Platforms: '))
-        node += nodes.Text(options['platform'], options['platform'])
-        ret.append(node)
-    # the synopsis isn't printed; in fact, it is only used in the
-    # modindex currently
-    if not noindex:
-        indextext = _('%s (module)') % modname
-        inode = addnodes.index(entries=[('single', indextext,
-                                         'module-' + modname, modname)])
-        ret.insert(0, inode)
-    return ret
 
-module_directive.arguments = (1, 0, 0)
+    def run(self):
-module_directive.options = {'platform': lambda x: x,
+        env = self.state.document.settings.env
-                            'synopsis': lambda x: x,
+        modname = self.arguments[0].strip()
-                            'noindex': directives.flag,
+        noindex = 'noindex' in self.options
-                            'deprecated': directives.flag}
-directives.register_directive('module', module_directive)
-
-
-def currentmodule_directive(name, arguments, options, content, lineno,
-                            content_offset, block_text, state, state_machine):
-    # This directive is just to tell people that we're documenting
-    # stuff in module foo, but links to module foo won't lead here.
-    env = state.document.settings.env
-    modname = arguments[0].strip()
-    if modname == 'None':
-        env.currmodule = None
-    else:
         env.currmodule = modname
-    return []
+        env.note_module(modname, self.options.get('synopsis', ''),
-
+                        self.options.get('platform', ''),
-currentmodule_directive.arguments = (1, 0, 0)
+                        'deprecated' in self.options)
-directives.register_directive('currentmodule', currentmodule_directive)
+        modulenode = addnodes.module()
+        modulenode['modname'] = modname
+        modulenode['synopsis'] = self.options.get('synopsis', '')
+        targetnode = nodes.target('', '', ids=['module-' + modname])
+        self.state.document.note_explicit_target(targetnode)
+        ret = [modulenode, targetnode]
+        if 'platform' in self.options:
+            platform = self.options['platform']
+            modulenode['platform'] = platform
+            node = nodes.paragraph()
+            node += nodes.emphasis('', _('Platforms: '))
+            node += nodes.Text(platform, platform)
+            ret.append(node)
+        # the synopsis isn't printed; in fact, it is only used in the
+        # modindex currently
+        if not noindex:
+            indextext = _('%s (module)') % modname
+            inode = addnodes.index(entries=[('single', indextext,
+                                             'module-' + modname, modname)])
+            ret.insert(0, inode)
+        return ret
 
 
-def author_directive(name, arguments, options, content, lineno,
+class CurrentModule(Directive):
-                     content_offset, block_text, state, state_machine):
+    """
-    # Show authors only if the show_authors option is on
+    This directive is just to tell Sphinx that we're documenting
-    env = state.document.settings.env
+    stuff in module foo, but links to module foo won't lead here.
-    if not env.config.show_authors:
+    """
-        return []
-    para = nodes.paragraph()
-    emph = nodes.emphasis()
-    para += emph
-    if name == 'sectionauthor':
-        text = _('Section author: ')
-    elif name == 'moduleauthor':
-        text = _('Module author: ')
-    else:
-        text = _('Author: ')
-    emph += nodes.Text(text, text)
-    inodes, messages = state.inline_text(arguments[0], lineno)
-    emph.extend(inodes)
-    return [para] + messages
 
-author_directive.arguments = (1, 0, 1)
+    has_content = False
-directives.register_directive('sectionauthor', author_directive)
+    required_arguments = 1
-directives.register_directive('moduleauthor', author_directive)
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
 
-
+    def run(self):
-def program_directive(name, arguments, options, content, lineno,
+        env = self.state.document.settings.env
-                      content_offset, block_text, state, state_machine):
+        modname = self.arguments[0].strip()
-    env = state.document.settings.env
+        if modname == 'None':
-    program = ws_re.sub('-', arguments[0].strip())
+            env.currmodule = None
-    if program == 'None':
-        env.currprogram = None
-    else:
-        env.currprogram = program
-    return []
-
-program_directive.arguments = (1, 0, 1)
-directives.register_directive('program', program_directive)
-
-
-# ------ index markup ----------------------------------------------------------
-
-indextypes = [
-    'single', 'pair', 'triple',
-]
-
-def index_directive(name, arguments, options, content, lineno,
-                    content_offset, block_text, state, state_machine):
-    arguments = arguments[0].split('\n')
-    env = state.document.settings.env
-    targetid = 'index-%s' % env.index_num
-    env.index_num += 1
-    targetnode = nodes.target('', '', ids=[targetid])
-    state.document.note_explicit_target(targetnode)
-    indexnode = addnodes.index()
-    indexnode['entries'] = ne = []
-    for entry in arguments:
-        entry = entry.strip()
-        for type in pairindextypes:
-            if entry.startswith(type+':'):
-                value = entry[len(type)+1:].strip()
-                value = pairindextypes[type] + '; ' + value
-                ne.append(('pair', value, targetid, value))
-                break
         else:
-            for type in indextypes:
+            env.currmodule = modname
+        return []
+
+
+class Author(Directive):
+    """
+    Directive to give the name of the author of the current document
+    or section. Shown in the output only if the show_authors option is on.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        env = self.state.document.settings.env
+        if not env.config.show_authors:
+            return []
+        para = nodes.paragraph()
+        emph = nodes.emphasis()
+        para += emph
+        if self.name == 'sectionauthor':
+            text = _('Section author: ')
+        elif self.name == 'moduleauthor':
+            text = _('Module author: ')
+        else:
+            text = _('Author: ')
+        emph += nodes.Text(text, text)
+        inodes, messages = self.state.inline_text(self.arguments[0],
+                                                  self.lineno)
+        emph.extend(inodes)
+        return [para] + messages
+
+
+class Program(Directive):
+    """
+    Directive to name the program for which options are documented.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        env = self.state.document.settings.env
+        program = ws_re.sub('-', self.arguments[0].strip())
+        if program == 'None':
+            env.currprogram = None
+        else:
+            env.currprogram = program
+        return []
+
+
+class Index(Directive):
+    """
+    Directive to add entries to the index.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    indextypes = [
+        'single', 'pair', 'triple',
+    ]
+
+    def run(self):
+        arguments = self.arguments[0].split('\n')
+        env = self.state.document.settings.env
+        targetid = 'index-%s' % env.index_num
+        env.index_num += 1
+        targetnode = nodes.target('', '', ids=[targetid])
+        self.state.document.note_explicit_target(targetnode)
+        indexnode = addnodes.index()
+        indexnode['entries'] = ne = []
+        for entry in arguments:
+            entry = entry.strip()
+            for type in pairindextypes:
                 if entry.startswith(type+':'):
                     value = entry[len(type)+1:].strip()
-                    ne.append((type, value, targetid, value))
+                    value = pairindextypes[type] + '; ' + value
+                    ne.append(('pair', value, targetid, value))
                     break
-            # shorthand notation for single entries
             else:
-                for value in entry.split(','):
+                for type in self.indextypes:
-                    value = value.strip()
+                    if entry.startswith(type+':'):
-                    if not value:
+                        value = entry[len(type)+1:].strip()
-                        continue
+                        ne.append((type, value, targetid, value))
-                    ne.append(('single', value, targetid, value))
+                        break
-    return [indexnode, targetnode]
+                # shorthand notation for single entries
-
+                else:
-index_directive.arguments = (1, 0, 1)
+                    for value in entry.split(','):
-directives.register_directive('index', index_directive)
+                        value = value.strip()
-
+                        if not value:
-# ------ versionadded/versionchanged -------------------------------------------
+                            continue
-
+                        ne.append(('single', value, targetid, value))
-def version_directive(name, arguments, options, content, lineno,
+        return [indexnode, targetnode]
-                      content_offset, block_text, state, state_machine):
-    node = addnodes.versionmodified()
-    node.document = state.document
-    node['type'] = name
-    node['version'] = arguments[0]
-    if len(arguments) == 2:
-        inodes, messages = state.inline_text(arguments[1], lineno+1)
-        node.extend(inodes)
-        if content:
-            state.nested_parse(content, content_offset, node)
-        ret = [node] + messages
-    else:
-        ret = [node]
-    env = state.document.settings.env
-    env.note_versionchange(node['type'], node['version'], node, lineno)
-    return ret
-
-version_directive.arguments = (1, 1, 1)
-version_directive.content = 1
-
-directives.register_directive('deprecated', version_directive)
-directives.register_directive('versionadded', version_directive)
-directives.register_directive('versionchanged', version_directive)
 
 
-# ------ see also --------------------------------------------------------------
+class VersionChange(Directive):
+    """
+    Directive to describe a change/addition/deprecation in a specific version.
+    """
 
-def seealso_directive(name, arguments, options, content, lineno,
+    has_content = True
-                      content_offset, block_text, state, state_machine):
+    required_arguments = 1
-    ret = make_admonition(
+    optional_arguments = 1
-        addnodes.seealso, name, [_('See also')], options, content,
+    final_argument_whitespace = True
-        lineno, content_offset, block_text, state, state_machine)
+    option_spec = {}
-    if arguments:
-        argnodes, msgs = state.inline_text(arguments[0], lineno)
-        para = nodes.paragraph()
-        para += argnodes
-        para += msgs
-        ret[0].insert(1, para)
-    return ret
 
-seealso_directive.content = 1
+    def run(self):
-seealso_directive.arguments = (0, 1, 1)
+        node = addnodes.versionmodified()
-directives.register_directive('seealso', seealso_directive)
+        node.document = self.state.document
+        node['type'] = self.name
+        node['version'] = self.arguments[0]
+        if len(self.arguments) == 2:
+            inodes, messages = self.state.inline_text(self.arguments[1],
+                                                      self.lineno+1)
+            node.extend(inodes)
+            if self.content:
+                self.state.nested_parse(self.content, self.content_offset, node)
+            ret = [node] + messages
+        else:
+            ret = [node]
+        env = self.state.document.settings.env
+        env.note_versionchange(node['type'], node['version'], node, self.lineno)
+        return ret
 
 
-# ------ production list (for the reference) -----------------------------------
+class SeeAlso(Directive):
+    """
+    An admonition mentioning things to look at as reference.
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        ret = make_admonition(
+            addnodes.seealso, self.name, [_('See also')], self.options,
+            self.content, self.lineno, self.content_offset, self.block_text,
+            self.state, self.state_machine)
+        if self.arguments:
+            argnodes, msgs = self.state.inline_text(self.arguments[0],
+                                                    self.lineno)
+            para = nodes.paragraph()
+            para += argnodes
+            para += msgs
+            ret[0].insert(1, para)
+        return ret
+
 
 token_re = re.compile('`([a-z_]+)`')
 
@@ -297,149 +344,202 @@ def token_xrefs(text, env):
         retnodes.append(nodes.Text(text[pos:], text[pos:]))
     return retnodes
 
-def productionlist_directive(name, arguments, options, content, lineno,
+class ProductionList(Directive):
-                             content_offset, block_text, state, state_machine):
+    """
-    env = state.document.settings.env
+    Directive to list grammar productions.
-    node = addnodes.productionlist()
+    """
-    messages = []
-    i = 0
 
-    for rule in arguments[0].split('\n'):
+    has_content = False
-        if i == 0 and ':' not in rule:
+    required_arguments = 1
-            # production group
+    optional_arguments = 0
-            continue
+    final_argument_whitespace = True
-        i += 1
+    option_spec = {}
-        try:
-            name, tokens = rule.split(':', 1)
-        except ValueError:
-            break
-        subnode = addnodes.production()
-        subnode['tokenname'] = name.strip()
-        if subnode['tokenname']:
-            idname = 'grammar-token-%s' % subnode['tokenname']
-            if idname not in state.document.ids:
-                subnode['ids'].append(idname)
-            state.document.note_implicit_target(subnode, subnode)
-            env.note_reftarget('token', subnode['tokenname'], idname)
-        subnode.extend(token_xrefs(tokens, env))
-        node.append(subnode)
-    return [node] + messages
 
-productionlist_directive.content = 0
+    def run(self):
-productionlist_directive.arguments = (1, 0, 1)
+        env = self.state.document.settings.env
-directives.register_directive('productionlist', productionlist_directive)
+        node = addnodes.productionlist()
+        messages = []
+        i = 0
 
-
+        for rule in self.arguments[0].split('\n'):
-# ------ glossary directive ----------------------------------------------------
+            if i == 0 and ':' not in rule:
-
+                # production group
-def glossary_directive(name, arguments, options, content, lineno,
-                       content_offset, block_text, state, state_machine):
-    """Glossary with cross-reference targets for :term: roles."""
-    env = state.document.settings.env
-    node = addnodes.glossary()
-    node.document = state.document
-    state.nested_parse(content, content_offset, node)
-
-    # the content should be definition lists
-    dls = [child for child in node if isinstance(child, nodes.definition_list)]
-    # now, extract definition terms to enable cross-reference creation
-    for dl in dls:
-        dl['classes'].append('glossary')
-        for li in dl.children:
-            if not li.children or not isinstance(li[0], nodes.term):
                 continue
-            termtext = li.children[0].astext()
+            i += 1
-            new_id = 'term-' + nodes.make_id(termtext)
+            try:
-            if new_id in env.gloss_entries:
+                name, tokens = rule.split(':', 1)
-                new_id = 'term-' + str(len(env.gloss_entries))
+            except ValueError:
-            env.gloss_entries.add(new_id)
+                break
-            li[0]['names'].append(new_id)
+            subnode = addnodes.production()
-            li[0]['ids'].append(new_id)
+            subnode['tokenname'] = name.strip()
-            state.document.settings.env.note_reftarget('term', termtext.lower(),
+            if subnode['tokenname']:
-                                                       new_id)
+                idname = 'grammar-token-%s' % subnode['tokenname']
-            # add an index entry too
+                if idname not in self.state.document.ids:
-            indexnode = addnodes.index()
+                    subnode['ids'].append(idname)
-            indexnode['entries'] = [('single', termtext, new_id, termtext)]
+                self.state.document.note_implicit_target(subnode, subnode)
-            li.insert(0, indexnode)
+                env.note_reftarget('token', subnode['tokenname'], idname)
-    return [node]
+            subnode.extend(token_xrefs(tokens, env))
-
+            node.append(subnode)
-glossary_directive.content = 1
+        return [node] + messages
-glossary_directive.arguments = (0, 0, 0)
-directives.register_directive('glossary', glossary_directive)
 
 
-# ------ miscellaneous markup --------------------------------------------------
+class Glossary(Directive):
+    """
+    Directive to create a glossary with cross-reference targets
+    for :term: roles.
+    """
 
-def centered_directive(name, arguments, options, content, lineno,
+    has_content = True
-                       content_offset, block_text, state, state_machine):
+    required_arguments = 0
-    if not arguments:
+    optional_arguments = 0
-        return []
+    final_argument_whitespace = False
-    subnode = addnodes.centered()
+    option_spec = {}
-    inodes, messages = state.inline_text(arguments[0], lineno)
-    subnode.extend(inodes)
-    return [subnode] + messages
 
-centered_directive.arguments = (1, 0, 1)
+    def run(self):
-directives.register_directive('centered', centered_directive)
+        env = self.state.document.settings.env
+        node = addnodes.glossary()
+        node.document = self.state.document
+        self.state.nested_parse(self.content, self.content_offset, node)
+
+        # the content should be definition lists
+        dls = [child for child in node
+               if isinstance(child, nodes.definition_list)]
+        # now, extract definition terms to enable cross-reference creation
+        for dl in dls:
+            dl['classes'].append('glossary')
+            for li in dl.children:
+                if not li.children or not isinstance(li[0], nodes.term):
+                    continue
+                termtext = li.children[0].astext()
+                new_id = 'term-' + nodes.make_id(termtext)
+                if new_id in env.gloss_entries:
+                    new_id = 'term-' + str(len(env.gloss_entries))
+                env.gloss_entries.add(new_id)
+                li[0]['names'].append(new_id)
+                li[0]['ids'].append(new_id)
+                env.note_reftarget('term', termtext.lower(), new_id)
+                # add an index entry too
+                indexnode = addnodes.index()
+                indexnode['entries'] = [('single', termtext, new_id, termtext)]
+                li.insert(0, indexnode)
+        return [node]
 
 
-def acks_directive(name, arguments, options, content, lineno,
+class Centered(Directive):
-                   content_offset, block_text, state, state_machine):
+    """
-    node = addnodes.acks()
+    Directive to create a centered line of bold text.
-    node.document = state.document
+    """
-    state.nested_parse(content, content_offset, node)
-    if len(node.children) != 1 or not isinstance(node.children[0],
-                                                 nodes.bullet_list):
-        return [state.document.reporter.warning('.. acks content is not a list',
-                                                line=lineno)]
-    return [node]
 
-acks_directive.content = 1
+    has_content = False
-acks_directive.arguments = (0, 0, 0)
+    required_arguments = 1
-directives.register_directive('acks', acks_directive)
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        if not self.arguments:
+            return []
+        subnode = addnodes.centered()
+        inodes, messages = self.state.inline_text(self.arguments[0],
+                                                  self.lineno)
+        subnode.extend(inodes)
+        return [subnode] + messages
 
 
-def hlist_directive(name, arguments, options, content, lineno,
-                    content_offset, block_text, state, state_machine):
-    ncolumns = options.get('columns', 2)
-    node = nodes.paragraph()
-    node.document = state.document
-    state.nested_parse(content, content_offset, node)
-    if len(node.children) != 1 or not isinstance(node.children[0],
-                                                 nodes.bullet_list):
-        return [state.document.reporter.warning(
-            '.. hlist content is not a list', line=lineno)]
-    fulllist = node.children[0]
-    # create a hlist node where the items are distributed
-    npercol, nmore = divmod(len(fulllist), ncolumns)
-    index = 0
-    newnode = addnodes.hlist()
-    for column in range(ncolumns):
-        endindex = index + (column < nmore and (npercol+1) or npercol)
-        col = addnodes.hlistcol()
-        col += nodes.bullet_list()
-        col[0] += fulllist.children[index:endindex]
-        index = endindex
-        newnode += col
-    return [newnode]
 
-hlist_directive.content = 1
+class Acks(Directive):
-hlist_directive.arguments = (0, 0, 0)
+    """
-hlist_directive.options = {'columns': int}
+    Directive for a list of names.
-directives.register_directive('hlist', hlist_directive)
+    """
+
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {}
+
+    def run(self):
+        node = addnodes.acks()
+        node.document = self.state.document
+        self.state.nested_parse(self.content, self.content_offset, node)
+        if len(node.children) != 1 or not isinstance(node.children[0],
+                                                     nodes.bullet_list):
+            return [self.state.document.reporter.warning(
+                '.. acks content is not a list', line=self.lineno)]
+        return [node]
 
 
-def tabularcolumns_directive(name, arguments, options, content, lineno,
+class HList(Directive):
-                             content_offset, block_text, state, state_machine):
+    """
-    # support giving explicit tabulary column definition to latex
+    Directive for a list that gets compacted horizontally.
-    node = addnodes.tabular_col_spec()
+    """
-    node['spec'] = arguments[0]
-    return [node]
 
-tabularcolumns_directive.content = 0
+    has_content = True
-tabularcolumns_directive.arguments = (1, 0, 1)
+    required_arguments = 0
-directives.register_directive('tabularcolumns', tabularcolumns_directive)
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        'columns': int,
+    }
 
+    def run(self):
+        ncolumns = self.options.get('columns', 2)
+        node = nodes.paragraph()
+        node.document = self.state.document
+        self.state.nested_parse(self.content, self.content_offset, node)
+        if len(node.children) != 1 or not isinstance(node.children[0],
+                                                     nodes.bullet_list):
+            return [self.state.document.reporter.warning(
+                '.. hlist content is not a list', line=self.lineno)]
+        fulllist = node.children[0]
+        # create a hlist node where the items are distributed
+        npercol, nmore = divmod(len(fulllist), ncolumns)
+        index = 0
+        newnode = addnodes.hlist()
+        for column in range(ncolumns):
+            endindex = index + (column < nmore and (npercol+1) or npercol)
+            col = addnodes.hlistcol()
+            col += nodes.bullet_list()
+            col[0] += fulllist.children[index:endindex]
+            index = endindex
+            newnode += col
+        return [newnode]
+
+
+class TabularColumns(Directive):
+    """
+    Directive to give an explicit tabulary column definition to LaTeX.
+    """
+
+    has_content = False
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    option_spec = {}
+
+    def run(self):
+        node = addnodes.tabular_col_spec()
+        node['spec'] = self.arguments[0]
+        return [node]
+
+
+directives.register_directive('toctree', TocTree)
+directives.register_directive('module', Module)
+directives.register_directive('currentmodule', CurrentModule)
+directives.register_directive('sectionauthor', Author)
+directives.register_directive('moduleauthor', Author)
+directives.register_directive('program', Program)
+directives.register_directive('index', Index)
+directives.register_directive('deprecated', VersionChange)
+directives.register_directive('versionadded', VersionChange)
+directives.register_directive('versionchanged', VersionChange)
+directives.register_directive('seealso', SeeAlso)
+directives.register_directive('productionlist', ProductionList)
+directives.register_directive('glossary', Glossary)
+directives.register_directive('centered', Centered)
+directives.register_directive('acks', Acks)
+directives.register_directive('hlist', HList)
+directives.register_directive('tabularcolumns', TabularColumns)
 
 # register the standard rst class directive under a different name