sphinx-contrib / feed / sphinxcontrib / feed /

# -*- coding: utf-8 -*-

    :copyright: Copyright 2007-2011 the Sphinx team, see AUTHORS.
    :license: BSD, see LICENSE for details.
    Latest is based on sphinx.directives.other.TocTree

import os

from docutils import nodes

from docutils.parsers.rst import Directive, directives

from feednodes import latest

class Latest(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.
    Used to be subclassed of TocTree, but now heavily modified from it, to
    avoid tedious bugs from TocTree's rather special role.
    has_content = True
    required_arguments = 0
    optional_arguments = 0
    final_argument_whitespace = False
    option_spec = {
        # 'maxdepth': int,
        'glob': directives.flag,
        # 'hidden': directives.flag,
        # 'numbered': int_or_nothing,
        'titlesonly': directives.flag,

    def run(self):
        env = self.state.document.settings.env
        suffix = env.config.source_suffix
        glob = 'glob' in self.options
        tocatts = tocnode.non_default_attributes()
        latestnode = latest()
        for key, val in tocatts.iteritems():
            latestnode[key] = val

        ret = []
        # (title, ref) pairs, where ref may be a document, or an external link,
        # and title may be None if the document's title is to be used
        entries = []
        includefiles = []
        all_docnames = env.found_docs.copy()
        # don't add the currently visited file in catch-all patterns
        for entry in self.content:
            if not entry:
            if not glob:
                # look for explicit titles ("Some Title <document>")
                m = explicit_title_re.match(entry)
                if m:
                    ref =
                    title =
                    docname = ref
                    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:
                        'toctree contains reference to nonexisting '
                        'document %r' % docname, line=self.lineno))
                    entries.append((title, docname))
                patname = docname_join(env.docname, entry)
                docnames = sorted(patfilter(all_docnames, patname))
                for docname in docnames:
                    all_docnames.remove(docname) # don't include it again
                    entries.append((None, docname))
                if not docnames:
                        'toctree glob pattern %r didn\'t match any documents'
                        % entry, line=self.lineno))
        subnode = addnodes.toctree()
        subnode['parent'] = env.docname
        # entries contains all entries (self references, external links etc.)
        subnode['entries'] = entries
        # includefiles only entries that are documents
        subnode['includefiles'] = includefiles
        subnode['maxdepth'] = self.options.get('maxdepth', -1)
        subnode['glob'] = glob
        subnode['hidden'] = 'hidden' in self.options
        subnode['numbered'] = self.options.get('numbered', 0)
        subnode['titlesonly'] = 'titlesonly' in self.options
        set_source_info(self, subnode)
        wrappernode = nodes.compound(classes=['latest-wrapper'])
        return ret