code reviewing for sphinx-users post: https://groups.google.com/d/msg/sphinx-users/vFpUgwj7bG0/Fyh5pPSY2iIJ

writernode.py

#!/usr/bin/env python

from docutils import nodes
from sphinx.util.compat import Directive, make_admonition

class writer(nodes.Admonition, nodes.Element):
    pass

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

def visit_writer_node(self, node):
    self.visit_admonition(node)

def depart_writer_node(self, node):
    self.depart_admonition(node)



class writerlistDirective(Directive):

    def run(self):
        return [writerlist('')]

class writerDirective(Directive):
    has_content = True

    def run(self):
        env = self.state.document.settings.env

        targetid = "writer-%d" % env.new_serialno('writer')
        targetnode = nodes.target('', '', ids=[targetid])

        ad = make_admonition(writer, self.name, ['writer'], self.options,
                             self.content, self.lineno, self.content_offset,
                             self.block_text, self.state, self.state_machine)

        if not hasattr(env, 'writer_all_writers'):
            env.writer_all_writers = []

        env.writer_all_writers.append({
            'docname': env.docname,
            'lineno': self.lineno,
            'writer': ad[0].deepcopy(),
            'target': targetnode})

        return [targetnode] + ad

def purge_writers(app, env, docmane):
    if not hasattr(env, 'writer_all_writers'):
        return

    env.writer_all_writers = [writer for writer in env.writer_all_writers
                              if writer['docname'] != docname]

def process_writer_nodes(app, doctree, fromdocname):
    env = app.builder.env

    for node in doctree.traverse(writerlist):
        content = []

        for writer_info in env.writer_all_writers:
            para = nodes.paragraph()
            filename = env.doc2path(writer_info['docname'], base=None)
            description = (
                ('(The original entry is located in %s, line %d and can be found' %
                 (filename, writer_info['lineno'])))
            para += nodes.Text(description, description)

            #create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis('here', 'here')
            newnode['refdocname'] = writer_info['docname']
            newnode['refuri'] = app.builder.get_relative_uri(
                fromdocname, writer_info['docname'])
            newnode['refuri'] += "#" + writer_info['target']['refid']
            newnode.append(innernode)
            para += newnode
            para += nodes.Text('.)', '.)')

            # insert the writerlist
            content.append(writer_info['writer'])
            content.append(para)

        node.replace_self(content)

def setup(app):
    app.add_node(writerlist)
    app.add_node(writer,
                 html=(visit_writer_node, depart_writer_node),
                 text=(visit_writer_node, depart_writer_node))

    app.add_directive('writer', writerDirective)
    app.add_directive('writerlist', writerlistDirective)
    app.connect('doctree-resolved', process_writer_nodes)
    app.connect('env-purge-doc', purge_writers)