directory list directive for Sphinx

index.rst

.. dir:: /tmp

/tmp

sphinxcontrib_dir.py

# -*- coding: utf-8 -*-
"""
    sphinxcontrib.dir
    ~~~~~~~~~~~~~~~~~~

    :copyright: Copyright 2012 by Takeshi KOMIYA
    :license: BSD, see LICENSE for details.
"""

import os

from docutils import nodes, utils
from docutils.parsers.rst import directives

from sphinx.util.compat import Directive


class directory(nodes.General, nodes.Element):
    pass


class DirDirective(Directive):
    """Directive for embedding google-maps"""

    has_content = False
    required_arguments = 0
    optional_arguments = 1
    final_argument_whitespace = True
    option_spec = {
    }

    def run(self):
        node = directory()
        if self.arguments:
            node['files'] = list(os.walk(self.arguments[0]))

        document = self.state.document
        if 'files' not in node:
            msg = 'dir directive needs argument for searching files'
            return [document.reporter.warning(msg, line=self.lineno)]

        return [node]


def visit_directory_node(self, node):
    def create_list(dirname, dirs, files):
        self.body.append('<ul>')

        for subdir in sorted(dirs[dirname][0]):
            self.body.append('<li>%s/</li>' % subdir)
            subdirname = os.path.join(dirname, subdir)
            create_list(subdirname, dirs, files)

        for file in sorted(dirs[dirname][1]):
            self.body.append('<li>%s</li>' % file)

        self.body.append('</ul>')

    basedir = node['files'][0][0]
    self.body.append('<ul>')
    self.body.append('<li>%s/</li>' % basedir)

    dirs = dict([dir, [subdirs, files]]
                for dir, subdirs, files in node['files'])
    create_list(basedir, dirs, node['files'])

    self.body.append('</ul>')


def depart_directory_node(self, node):
    pass


def setup(app):
    app.add_node(directory,
                 html=(visit_directory_node, depart_directory_node))
    app.add_directive('dir', DirDirective)