changeset 1217:c0515c0dfef9

Wrote a sphinx extension for a taglist directive that outputs a javascript tag list and related functions
author boulanni <nicolas_boulanger@hotmail.com>
date Wed, 22 Sep 2010 12:49:41 -0400
parents 5a8930e089ed
children 5d1b5906151c
files doc/conf.py doc/index.txt doc/taglist.py
diffstat 3 files changed, 74 insertions(+), 1 deletions(-) [+]
line wrap: on
line diff
--- a/doc/conf.py	Wed Sep 22 12:12:30 2010 -0400
+++ b/doc/conf.py	Wed Sep 22 12:49:41 2010 -0400
@@ -23,7 +23,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'ext']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'ext', 'taglist']
 
 todo_include_todos = True
 
--- a/doc/index.txt	Wed Sep 22 12:12:30 2010 -0400
+++ b/doc/index.txt	Wed Sep 22 12:49:41 2010 -0400
@@ -19,6 +19,10 @@
 
 The ``pylearn`` subfolder should be on your ``$PYTHONPATH``.
 
+Tags list
+==========
+.. taglist:: 
+
 Documentation
 =============
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/taglist.py	Wed Sep 22 12:49:41 2010 -0400
@@ -0,0 +1,69 @@
+
+from docutils import nodes
+from sphinx.util.compat import Directive
+from collections import defaultdict
+
+def taglist_html(self, node):
+    env = app.builder.env
+    if not hasattr(env, 'tags_db'): return
+    
+    self.body.append("""
+        <script langage=javascript>
+        var cur = null;
+        var cura = null;
+        function change(a1, div1){
+          nexta = document.getElementById(a1)
+          next = document.getElementById(div1)
+          if (cur != null) { cur.style.display = 'none'; cura.style.fontWeight = 'normal'; }
+          if (cur != next) { next.style.display = 'block'; nexta.style.fontWeight = 'bold'; cur = next; cura = nexta; }
+          else cur = null
+        }
+        </script>
+        """)
+
+    for tag in sorted(env.tags_db):
+        tid = tag.replace(' ','_')
+        self.body.append(""" <a id=a_%s href="javascript:change('a_%s', 'div_%s')">%s</a> &nbsp;""" % (tid, tid, tid, tag))
+
+    for tag in env.tags_db:
+        tid = tag.replace(' ','_')
+        self.body.append('<div id=div_%s style="display:none;"><br>' % (tid,))
+        for f in sorted(env.tags_db[tag], lambda f,g: cmp(f[1], g[1])):
+            uri = app.builder.get_relative_uri(node.docname, f[0]) + '#' + f[1]
+            self.body.append('<a href="%s">%s</a><br>' % (uri, f[1]))
+        self.body.append('</div>')
+
+class taglist_node(nodes.Element): pass
+
+class taglist(Directive):
+    def run(self):
+        a = taglist_node()
+        a.docname = app.builder.env.docname
+        return [a]
+
+def purge_tags(app, env, docname):
+    if not hasattr(env, 'tags_db'): return
+
+    for tag in env.tags_db:
+        for f in [f for f in env.tags_db[tag]]:
+            if f[0]==docname: env.tags_db[tag].remove(f)
+
+def autodoc_process_docstring(app, what, name, obj, options, lines):
+    env = app.builder.env
+    if not hasattr(env, 'tags_db'):
+        env.tags_db = defaultdict(set)
+
+    if what == 'function':
+        for tag in obj.tags:
+            env.tags_db[tag].add((env.docname, name))
+
+def setup(app_):
+    global app
+    app = app_
+
+    app.add_node(taglist_node, html=(taglist_html, lambda a,b:None))
+    app.add_directive('taglist', taglist)
+    app.connect('env-purge-doc', purge_tags)
+    app.connect('autodoc-process-docstring', autodoc_process_docstring)
+    
+