--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/buildframework/helium/external/python/lib/common/Sphinx-0.5.1-py2.5.egg/sphinx/ext/todo.py Wed Dec 23 19:29:07 2009 +0200
@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""
+ sphinx.ext.todo
+ ~~~~~~~~~~~~~~~
+
+ Allow todos to be inserted into your documentation. Inclusion of todos can
+ be switched of by a configuration variable. The todolist directive collects
+ all todos of your project and lists them along with a backlink to the
+ original location.
+
+ :copyright: 2008 Daniel Bültmann.
+ :license: BSD.
+"""
+
+from docutils import nodes
+
+from sphinx.util.compat import make_admonition
+
+class todo_node(nodes.Admonition, nodes.Element): pass
+class todolist(nodes.General, nodes.Element): pass
+
+
+def todo_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ env = state.document.settings.env
+
+ targetid = "todo-%s" % env.index_num
+ env.index_num += 1
+ targetnode = nodes.target('', '', ids=[targetid])
+
+ ad = make_admonition(todo_node, name, [_('Todo')], options, content, lineno,
+ content_offset, block_text, state, state_machine)
+
+ # Attach a list of all todos to the environment,
+ # the todolist works with the collected todo nodes
+ if not hasattr(env, 'todo_all_todos'):
+ env.todo_all_todos = []
+ env.todo_all_todos.append({
+ 'docname': env.docname,
+ 'lineno': lineno,
+ 'todo': ad[0].deepcopy(),
+ 'target': targetnode,
+ })
+
+ return [targetnode] + ad
+
+
+def todolist_directive(name, arguments, options, content, lineno,
+ content_offset, block_text, state, state_machine):
+ # Simply insert an empty todolist node which will be replaced later
+ # when process_todo_nodes is called
+ return [todolist('')]
+
+
+def process_todo_nodes(app, doctree, fromdocname):
+ if not app.config['todo_include_todos']:
+ for node in doctree.traverse(todo_node):
+ node.parent.remove(node)
+
+ # Replace all todolist nodes with a list of the collected todos.
+ # Augment each todo with a backlink to the original location.
+ env = app.builder.env
+
+ for node in doctree.traverse(todolist):
+ if not app.config['todo_include_todos']:
+ node.replace_self([])
+ continue
+
+ content = []
+
+ for todo_info in env.todo_all_todos:
+ para = nodes.paragraph()
+ filename = env.doc2path(todo_info['docname'], base=None)
+ description = (
+ _('(The original entry is located in %s, line %d and can be found ') %
+ (filename, todo_info['lineno']))
+ para += nodes.Text(description, description)
+
+ # Create a reference
+ newnode = nodes.reference('', '')
+ innernode = nodes.emphasis(_('here'), _('here'))
+ newnode['refdocname'] = todo_info['docname']
+ newnode['refuri'] = app.builder.get_relative_uri(
+ fromdocname, todo_info['docname'])
+ newnode['refuri'] += '#' + todo_info['target']['refid']
+ newnode.append(innernode)
+ para += newnode
+ para += nodes.Text('.)', '.)')
+
+ # Insert into the todolist
+ content.append(todo_info['todo'])
+ content.append(para)
+
+ node.replace_self(content)
+
+
+def purge_todos(app, env, docname):
+ if not hasattr(env, 'todo_all_todos'):
+ return
+ env.todo_all_todos = [todo for todo in env.todo_all_todos
+ if todo['docname'] != docname]
+
+
+def visit_todo_node(self, node):
+ self.visit_admonition(node)
+
+def depart_todo_node(self, node):
+ self.depart_admonition(node)
+
+def setup(app):
+ app.add_config_value('todo_include_todos', False, False)
+
+ app.add_node(todolist)
+ app.add_node(todo_node,
+ html=(visit_todo_node, depart_todo_node),
+ latex=(visit_todo_node, depart_todo_node),
+ text=(visit_todo_node, depart_todo_node))
+
+ app.add_directive('todo', todo_directive, 1, (0, 0, 1))
+ app.add_directive('todolist', todolist_directive, 0, (0, 0, 0))
+ app.connect('doctree-resolved', process_todo_nodes)
+ app.connect('env-purge-doc', purge_todos)
+