Merge pull request #2859 from jessica-mitchell/add-ext-sphinx

Add custom Sphinx extension that lists examples based on model name

doc/htmldoc/_ext/extractor_userdocs.py

@@ -31,8 +31,9 @@
 import logging
 from collections import Counter
 
+
 logging.basicConfig(level=logging.WARNING)
-log = logging.getLogger()
+log = logging.getLogger(__name__)
 
 
 def relative_glob(*pattern, basedir=os.curdir, **kwargs):

doc/htmldoc/_ext/list_examples.py

@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+#
+# list_examples.py
+#
+# This file is part of NEST.
+#
+# Copyright (C) 2004 The NEST Initiative
+#
+# NEST is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+#
+# NEST is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with NEST.  If not, see <http://www.gnu.org/licenses/>.
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, Parser
+
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+import os
+import glob
+
+import logging
+
+logging.basicConfig(level=logging.WARNING)
+log = logging.getLogger(__name__)
+
+
+class listnode(nodes.General, nodes.Element):
+    pass
+
+
+def ProcessExamples(app, doctree, docname):
+    # Create the bullet list of examples, sorted by title
+    # given by the model name in the directive argument
+
+    env = app.builder.env
+    examples_titles_map = {}
+
+    try:
+        models_to_examples_map = ModelMatchExamples()
+
+        for node in doctree.findall(listnode):
+            for requested_list in env.list_examples_directive_requests:
+                # compare current location with attribute location to get
+                # correct model name
+                if requested_list["name"] == docname:
+                    if requested_list["model_name"] not in models_to_examples_map:
+                        log.info("No examples found for Model: " + requested_list["model_name"])
+                        bullet_list = nodes.Text("None")
+                        break
+
+                    list_of_examples = models_to_examples_map[requested_list["model_name"]]
+                    for value in list_of_examples:
+                        mydocname = os.path.splitext(value)[0]
+                        examples_titles_map[mydocname] = str(env.titles[mydocname].children[0])
+                sorted_examples = dict(sorted(examples_titles_map.items(), key=lambda kv: kv[1]))
+                bullet_list = nodes.bullet_list()
+
+                for filename, title in sorted_examples.items():
+                    # Create a reference node that links to the example
+                    # equivalent to HTML <li>
+                    list_item = nodes.list_item()
+                    newnode = nodes.reference("", "")
+                    newnode["internal"] = True
+                    newnode["refdocname"] = filename
+                    newnode["refuri"] = app.builder.get_relative_uri(docname, filename)
+                    newnode.append(nodes.Text(title))
+                    para = nodes.paragraph()
+                    para += newnode
+                    list_item.append(para)
+                    bullet_list += list_item
+
+            node.replace_self(bullet_list)
+
+    except Exception as e:
+        log.warning(repr(e))
+        log.warning("exception of class: %s", e.__class__)
+        raise
+
+
+def ModelMatchExamples():
+    # Get list of models and search the examples directory for matches
+
+    filepath_models = "../../models/"
+    filepath_examples = "auto_examples/"
+
+    model_files = []
+    for filename in os.listdir(filepath_models):
+        if filename.endswith(".h"):
+            model_files.append(os.path.splitext(filename)[0])
+
+    matches = {}
+    files = glob.glob(filepath_examples + "**/*.rst", recursive=True)
+    for filename in files:
+        if "auto_examples/index" in filename:
+            continue
+        with open(filename, "r", errors="ignore") as file:
+            content = file.read()
+            for model_file in model_files:
+                if model_file in content:
+                    matches.setdefault(model_file, []).append(filename)
+
+    return matches
+
+
+class ListExamplesDirective(SphinxDirective):
+    # Provide a list of the examples that contain the given model name.
+    # The model name is the required argument in the directive
+    # (.. listexamples:: model_name). No options, nor content is expected.
+
+    has_content = False
+    required_arguments = 1
+    option_spec = {}
+
+    def run(self):
+        model_arg = self.arguments[0]
+
+        if not hasattr(self.env, "list_examples_directive_requests"):
+            self.env.list_examples_directive_requests = []
+
+        # See TODO tutorial in Sphinx for more info.
+        # Using environment attribute list_examples_directive_requests to store argument and
+        # its location (docname)
+        self.env.list_examples_directive_requests.append({"model_name": model_arg, "name": self.env.docname})
+
+        return [listnode("")]
+
+
+def setup(app):
+    # Note that the directive names need to be all lower case
+    app.add_directive("listexamples", ListExamplesDirective)
+    app.add_node(listnode)
+    app.connect("doctree-resolved", ProcessExamples)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/htmldoc/conf.py

@@ -48,6 +48,7 @@
 master_doc = "index"
 extensions = [
     "sphinx_gallery.gen_gallery",
+    "list_examples",
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "sphinx.ext.autosummary",

models/ac_generator.h

@@ -105,6 +105,11 @@ See also
 dc_generator, noise_generator, step_current_generator, StimulationDevice,
 Device
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: ac_generator
+
 EndUserDocs */
 
 namespace nest

models/aeif_cond_alpha.h

@@ -185,6 +185,11 @@ See also
 
 iaf_cond_alpha, aeif_cond_exp
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_cond_alpha
+
 EndUserDocs */
 
 class aeif_cond_alpha : public ArchivingNode

models/aeif_cond_alpha_multisynapse.h

@@ -160,6 +160,11 @@ See also
 
 aeif_cond_alpha_multisynapse
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_cond_alpha_multisynapse
+
 EndUserDocs */
 
 namespace nest

models/aeif_cond_beta_multisynapse.h

@@ -177,6 +177,11 @@ See also
 
 aeif_cond_alpha_multisynapse
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_cond_beta_multisynapse
+
 EndUserDocs */
 
 class aeif_cond_beta_multisynapse : public ArchivingNode

models/aeif_cond_exp.h

@@ -186,6 +186,11 @@ See also
 
 iaf_cond_exp, aeif_cond_alpha
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_cond_exp
+
 EndUserDocs */
 
 class aeif_cond_exp : public ArchivingNode

models/aeif_psc_alpha.h

@@ -176,6 +176,11 @@ See also
 
 iaf_psc_alpha, aeif_cond_exp
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_psc_alpha
+
 EndUserDocs */
 
 class aeif_psc_alpha : public ArchivingNode

models/aeif_psc_delta.h

@@ -165,6 +165,11 @@ See also
 
 iaf_psc_delta, aeif_cond_exp, aeif_psc_exp
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_psc_delta
+
 EndUserDocs */
 
 class aeif_psc_delta : public ArchivingNode

models/aeif_psc_delta_clopath.h

@@ -196,6 +196,11 @@ See also
 
 aeif_psc_delta, clopath_synapse, hh_psc_alpha_clopath
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_psc_delta_clopath
+
 EndUserDocs */
 
 class aeif_psc_delta_clopath : public ClopathArchivingNode

models/aeif_psc_exp.h

@@ -173,6 +173,11 @@ See also
 
 iaf_psc_exp, aeif_cond_exp
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: aeif_psc_exp
+
 EndUserDocs */
 
 class aeif_psc_exp : public ArchivingNode

models/bernoulli_synapse.h

@@ -86,6 +86,11 @@ See also
 
 static_synapse, static_synapse_hom_w
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: bernoulli_synapse
+
 EndUserDocs */
 
 template < typename targetidentifierT >

models/clopath_synapse.h

@@ -105,6 +105,11 @@ See also
 
 stdp_synapse, aeif_psc_delta_clopath, hh_psc_alpha_clopath
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: iaf_psc_alpha
+
 EndUserDocs */
 
 // connections are templates of target identifier type (used for pointer /

models/cm_default.h

@@ -223,6 +223,11 @@ See also
 
 NEURON simulator ;-D
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: cm_default
+
 EndUserDocs*/
 
 class cm_default : public ArchivingNode

models/cont_delay_synapse.h

@@ -71,6 +71,11 @@ See also
 
 static_synapse, iaf_psc_alpha_ps
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: cont_delay_synapse
+
 EndUserDocs */
 
 template < typename targetidentifierT >

models/correlation_detector.h

@@ -140,6 +140,11 @@ See also
 
 spike_recorder
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: correlation_detector
+
 EndUserDocs */
 
 /**

models/correlomatrix_detector.h

@@ -130,6 +130,11 @@ See also
 
 correlation_detector, spike_recorder
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: correlomatrix_detector
+
 EndUserDocs */
 
 /**

models/correlospinmatrix_detector.h

@@ -120,6 +120,11 @@ See also
 
 correlation_detector, correlomatrix_detector, spike_recorder
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: correlospinmatrix_detector
+
 EndUserDocs */
 
 /**

models/dc_generator.h

@@ -82,6 +82,11 @@ See also
 
 ac_generator, noise_generator, step_current_generator
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: dc_generator
+
 EndUserDocs */
 
 class dc_generator : public StimulationDevice

models/diffusion_connection.h

@@ -82,6 +82,11 @@ See also
 
 siegert_neuron, rate_connection_instantaneous
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: diffusion_connection
+
 EndUserDocs */
 
 template < typename targetidentifierT >

models/erfc_neuron.h

@@ -123,6 +123,11 @@ CurrentEvent
 See also
 ++++++++
 
+Examples using this model
++++++++++++++++++++++++++
+
+.. listexamples:: erfc_neuron
+
 
 EndUserDocs */