Add the sphinx extension numfig.

documentations/userguide/conf.py

@@ -20,8 +20,8 @@ import re
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-
+sys.path.insert(0, os.path.abspath('.'))
+print sys.path
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -29,7 +29,7 @@ import re
 
 # 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.todo', 'sphinx.ext.mathjax']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'numfig']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -184,10 +184,10 @@ htmlhelp_basename = 'track_eventsdoc'
 
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+'pointsize': '11pt',
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
@@ -206,7 +206,7 @@ latex_documents = [
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+latex_use_parts = False
 
 # If true, show page references after internal links.
 #latex_show_pagerefs = False

documentations/userguide/numfig.py

+from docutils.nodes import figure, caption, Text, reference, raw, SkipNode, Element
+from sphinx.roles import XRefRole
+
+
+# Element classes
+
+class page_ref(reference):
+    pass
+
+class num_ref(reference):
+    pass
+
+
+# Visit/depart functions
+
+def skip_page_ref(self, node):
+    raise SkipNode
+
+def latex_visit_page_ref(self, node):
+    self.body.append("\\pageref{%s:%s}" % (node['refdoc'], node['reftarget']))
+    raise SkipNode
+
+def latex_visit_num_ref(self, node):
+    fields = node['reftarget'].split('#')
+    if len(fields) > 1:
+        label, target = fields
+        ref_link = '%s:%s' % (node['refdoc'], target)
+        latex = "\\hyperref[%s]{%s \\ref*{%s}}" % (ref_link, label, ref_link)
+        self.body.append(latex)
+    else:
+        self.body.append('\\ref{%s:%s}' % (node['refdoc'], fields[0]))
+
+    raise SkipNode
+
+
+def doctree_read(app, doctree):
+    # first generate figure numbers for each figure
+    env = app.builder.env
+    figid_docname_map = getattr(env, 'figid_docname_map', {})
+
+    for figure_info in doctree.traverse(figure):
+        for id in figure_info['ids']:
+            figid_docname_map[id] = env.docname
+
+    env.figid_docname_map = figid_docname_map
+
+
+def doctree_resolved(app, doctree, docname):
+    i = 1
+    figids = {}
+    for figure_info in doctree.traverse(figure):
+        if app.builder.name != 'latex' and app.config.number_figures:
+            for cap in figure_info.traverse(caption):
+                cap[0] = Text("%s %d: %s" % (app.config.figure_caption_prefix, i, cap[0]))
+
+        for id in figure_info['ids']:
+            figids[id] = i
+
+        i += 1
+
+
+    # replace numfig nodes with links
+    if app.builder.name != 'latex':
+        for ref_info in doctree.traverse(num_ref):
+            if '#' in ref_info['reftarget']:
+                label, target = ref_info['reftarget'].split('#')
+                labelfmt = label + " %d"
+            else:
+                labelfmt = '%d'
+                target = ref_info['reftarget']
+
+            if target not in figids:
+                continue
+
+            if app.builder.name == 'html':
+                target_doc = app.builder.env.figid_docname_map[target]
+                link = "%s#%s" % (app.builder.get_relative_uri(docname, target_doc),
+                                  target)
+                html = '<a class="pageref" href="%s">%s</a>' % (link, labelfmt %(figids[target]))
+                ref_info.replace_self(raw(html, html, format='html'))
+            else:
+                ref_info.replace_self(Text(labelfmt % (figids[target])))
+
+
+def clean_env(app):
+    app.builder.env.i=1
+    app.builder.env.figid_docname_map = {}
+
+def setup(app):
+    app.add_config_value('number_figures', True, True)
+    app.add_config_value('figure_caption_prefix', "Figure", True)
+
+    app.add_node(page_ref,
+                 text=(skip_page_ref, None),
+                 html=(skip_page_ref, None),
+                 latex=(latex_visit_page_ref, None))
+
+    app.add_role('page', XRefRole(nodeclass=page_ref))
+
+    app.add_node(num_ref,
+                 latex=(latex_visit_num_ref, None))
+
+    app.add_role('num', XRefRole(nodeclass=num_ref))
+
+    app.connect("builder-inited", clean_env)
+    app.connect('doctree-read', doctree_read)
+    app.connect('doctree-resolved', doctree_resolved)