Merge pull request #424 from brian-team/auto_link_to_tutorials

Example finder now finds tutorials as well as examples

brian2/sphinxext/examplefinder.py

@@ -10,43 +10,63 @@
 __all__ = ['auto_find_examples']
 
 the_examples_map = defaultdict(list)
+the_tutorials_map = defaultdict(list)
 
-def get_examples_map():
-    if the_examples_map:
-        return the_examples_map
-    if 'BRIAN2_DOCS_EXAMPLE_DIR' in os.environ:
-        rootdir = os.environ['BRIAN2_DOCS_EXAMPLE_DIR']
+def get_map(environ_var, relrootdir, pattern, the_map, path_exclusions=[]):
+    if the_map:
+        return the_map
+    if environ_var in os.environ:
+        rootdir = os.environ[environ_var]
     else:
         rootdir, _ = os.path.split(__file__)
-        rootdir = os.path.normpath(os.path.join(rootdir, '../../examples'))
-    fnames = [fname for fname in GlobDirectoryWalker(rootdir, '*.py')]
+        rootdir = os.path.normpath(os.path.join(rootdir, relrootdir))
+    fnames = [fname for fname in GlobDirectoryWalker(rootdir, '*'+pattern)]
+    for exclude in path_exclusions:
+        fnames = [fname for fname in fnames if exclude not in fname]
     shortfnames = [os.path.relpath(fname, rootdir) for fname in fnames]
-    exnames = [fname.replace('/', '.').replace('\\', '.').replace('.py', '') for fname in shortfnames]
+    exnames = [fname.replace('/', '.').replace('\\', '.').replace(pattern, '') for fname in shortfnames]
     for fname, shortfname, exname in zip(fnames, shortfnames, exnames):
         ex = open(fname, 'r').read()
         ids = get_identifiers(ex)
         for id in ids:
-            the_examples_map[id].append((shortfname.replace('\\', '/'), exname))
-    return the_examples_map
+            the_map[id].append((shortfname.replace('\\', '/'), exname))
+    return the_map
+
+
+def get_examples_map():
+    return get_map('BRIAN2_DOCS_EXAMPLE_DIR', '../../examples', '.py', the_examples_map)
+
+
+def get_tutorials_map():
+    return get_map('BRIAN2_DOCS_TUTORIALS_DIR', '../../tutorials', '.ipynb', the_tutorials_map,
+                   path_exclusions=['.ipynb_checkpoints'])
+
 
 def auto_find_examples(obj, headersymbol='='):
     '''
-    Returns a restructured text section listing all the examples making use
-    of the specified object (as determined by the name being in the list
-    of identifiers, which may occasionally make mistakes but is usually
-    going to be correct).
+    Returns a restructured text section listing all the examples and
+    tutorials making use of the specified object (as determined by
+    the name being in the list of identifiers, which may occasionally
+    make mistakes but is usually going to be correct).
     '''
     name = obj.__name__
     examples_map = get_examples_map()
     examples = the_examples_map[name]
-    if len(examples)==0:
+    tutorials_map = get_tutorials_map()
+    tutorials = the_tutorials_map[name]
+    if len(examples+tutorials)==0:
         return ''
-    txt = 'Examples using this'
+    txt = 'Tutorials and examples using this'
     txt = txt+'\n'+headersymbol*len(txt)+'\n\n'
-    for ex in examples:
-        txt += '* :doc:`%s </examples/%s>`\n' % ex
+    for tutname, tutloc in tutorials:
+        tutname = tutname.replace('.ipynb', '')
+        txt += '* Tutorial :doc:`%s </resources/tutorials/%s>`\n' % (tutname, tutloc)
+    for exname, exloc in examples:
+        exname = exname.replace('.py', '')
+        txt += '* Example :doc:`%s </examples/%s>`\n' % (exname, exloc)
     return txt+'\n'
 
+
 if __name__=='__main__':
     from brian2 import NeuronGroup, SpatialNeuron
-    print auto_find_examples(SpatialNeuron)
+    print auto_find_examples(NeuronGroup)