Sphinx gallery migration - GSoC 2026 project #2

docs_sphinx/.gitignore

@@ -3,3 +3,4 @@
 /examples
 /examples_images
 /tutorials
+backreferences/

docs_sphinx/conf.py

@@ -101,6 +101,8 @@ def __getattr__(cls, name):
     "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
     "sphinx_tabs.tabs",
+    "sphinx_gallery.gen_gallery",
+    "sphinx.ext.napoleon",
 ]
 
 # Set readthedocs theme if available
@@ -348,3 +350,24 @@ def __getattr__(cls, name):
 
 # Configure linking to github
 extlinks = {"issue": ("https://github.com/brian-team/brian2/issues/%s", "# %s")}
+
+sphinx_gallery_conf = {
+     'examples_dirs': '../examples',   #path to example scripts
+     'gallery_dirs': 'examples',  # path to where to save gallery generated output
+     'filename_pattern': '/plot_',
+     'backreferences_dir': 'gen_modules/backreferences',
+     'reference_url': {
+        # The module you locally document uses a None
+        'brian2': None,
+        # External python modules use their documentation websites
+        'matplotlib': 'https://matplotlib.org',
+        'numpy': 'https://docs.scipy.org/doc/numpy'
+    },
+    # Modules for which function level galleries are created.  In
+    # this case sphinx_gallery and numpy in a tuple of strings.
+    'doc_module': ('brian2'),
+    'plot_gallery': False,
+    }
+# generate autosummary even if no references
+autosummary_generate = True
+

docs_sphinx/developer/guidelines/representation.rst

@@ -45,7 +45,7 @@ to work, they should use an underscore for subscripts and two underscores for su
 Sympy's printer supports formatting arbitrary objects, all they have to do is to implement a
 ``_latex`` method (no trailing underscore). For most Brian objects, this is unnecessary as they will
 never be formatted with sympy's LaTeX printer. For some core objects, in particular the units,
-is is useful, however, as it can be reused in LaTeX representations for ipython (see below).
+it is useful, however, as it can be reused in LaTeX representations for ipython (see below).
 Note that the ``_latex`` method should not return ``$`` or ``\begin{equation}`` (sympy's method
 includes a ``mode`` argument that wraps the output automatically).
 

docs_sphinx/introduction/brian1_to_2/neurongroup.rst

@@ -107,7 +107,7 @@ code generation mechanism provides (in addition to not being able to use
 +    def single_threshold(v):                                             |    @check_units(v=volt, result=bool)                            |
 +        # Only let a single neuron spike                                 |    def single_threshold(v):                                     |
 +        crossed_threshold = np.nonzero(v > -50*mV)[0]                    |        pass # ... (identical to Brian 1)                        |
-+        should_spike = np.zeros(len(P), dtype=bool)                   |                                                                 |
++        should_spike = np.zeros(len(P), dtype=bool)                      |                                                                 |
 +        if len(crossed_threshold):                                       |    @check_units(spikes=1, result=1)                             |
 +            choose = np.random.randint(len(crossed_threshold))           |    def global_reset(spikes):                                    |
 +            should_spike[crossed_threshold[choose]] = True               |        # Reset everything                                       |

examples/GALLERY_HEADER.rst

@@ -0,0 +1,5 @@
+Brian 2 Examples
+================
+
+This gallery contains examples demonstrating how to use
+:mod:`brian2` to build and simulate spiking neural networks.