Add introductory text for models in documentation

doc/extractor_userdocs.py

@@ -131,7 +131,7 @@ def UserDocExtractor(
             try:
                 doc = rewrite_see_also(doc, filename, tags)
             except ValueError as e:
-                log.warning("Failed to rebuild 'See also' section: %s", e)
+                log.info("Failed to rebuild 'See also' section: %s", e)
             write_rst_files(doc, tags, outdir, outname)
 
     log.info("%4d tags found:\n%s", len(tagdict), pformat(list(tagdict.keys())))
@@ -239,7 +239,7 @@ def rightcase(text):
             secend = nexttitle.start()
         original = doc[secstart:secend].strip().replace('\n', ' ')
         if original:
-            log.warning("dropping manual 'see also' list in %s user docs: '%s'", filename, original)
+            log.info("dropping manual 'see also' list in %s user docs: '%s'", filename, original)
         return (
             doc[:secstart] +
             "\n" + ", ".join([":doc:`{taglabel} <index_{tag}>`".format(tag=tag, taglabel=rightcase(tag))
@@ -344,11 +344,17 @@ def mkitem(t):
 
     output = list()
     if top:
-        page_title = "Model Directory"
+        page_title = "Model directory"
+        description = """
+                       The models are organized and autogenerated by keywords (e.g., adaptive threshold,
+                       conductance-based etc.). Models that contain a specific keyword will be listed under that word.
+                       For more information on models, see our :ref:`intro to NEST models <modelsmain>`.
+                       """
         if len(hierarchy.keys()) == 1:
             page_title += ": " + ", ".join(current_tags)
         output.append(page_title)
         output.append(underlines[0]*len(page_title)+"\n")
+        output.append(description + "\n")
         if len(hierarchy.keys()) != 1:
             underlines = underlines[1:]
 

doc/htmldoc/installation/index.rst

@@ -19,7 +19,7 @@ Install NEST
 
 .. grid:: 1 1 2 2
 
-    .. grid-item-card:: |admin| Install NEST for supercomputers and clusters 
+    .. grid-item-card:: |admin| Install NEST for supercomputers and clusters
        :class-title: sd-d-flex-row sd-align-minor-center
 
        I'm an admin or user who wants to :ref:`run NEST on HPC <admin_install>`
@@ -29,8 +29,20 @@ Install NEST
 
        I'm a developer who wants to :ref:`do development in NEST <dev_install>`
 
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: |nestml| Install NEST with NESTML
+       :class-title: sd-d-flex-row sd-align-minor-center
+
+       I'm a user who wants to :doc:`create or customize models <nestml:installation>`
+
+|
+
+
+
 ----
 
+
 If installation didn't work, see the :ref:`troubleshooting section <troubleshooting>`.
 
 
@@ -48,3 +60,5 @@ If installation didn't work, see the :ref:`troubleshooting section <troubleshoot
 .. |teacher| image:: ../static/img/014-teacher.svg
 .. |admin| image:: ../static/img/001-shuttle.svg
 .. |dev| image:: ../static/img/dev_orange.svg
+.. |nestml| image:: ../static/img/nestml-logo.png
+      :scale: 15%

doc/htmldoc/models/models-main.rst

@@ -1,12 +1,93 @@
+.. _modelsmain:
+
 Models in NEST
 ==============
 
 
+What we mean by `models`
+------------------------
+
+Models in the context of NEST are C++ implementations of mathematical equations that describe the characteristics and behavior of
+different types of neurons and synapses, based on the relevant peer-reviewed publications for the model.
+
+We also use the term model in relation to network models (e.g., :ref:`microcircuit <toc_microcircuit>` and `multi-area model <https://inm-6.github.io/multi-area-model/>`_). These network models
+can be considered a level of complexity higher than the neuron or synapse model. We do not focus on network models here.
+
+Find a model
+------------
+
 NEST provides a ton of models! Textbook standards like integrate-and-fire and Hodgkin-Huxley type models are available
 alongside high quality implementations of models published by the neuroscience community.
+The models are organized and autogenerated by keywords (e.g., :doc:`adaptive threshold <index_adaptive threshold>`, :doc:`conductance-based <index_conductance-based>` etc) in our directory. 
+Models that contain a specific keyword will be listed under that word.
+
+.. seealso::
+
+   Discover :doc:`all the models in our directory <index>`.
+
+Create and customize models with NESTML
+---------------------------------------
+
+Check out :doc:`NESTML <nestml:index>`, a domain-specific language for neuron and synapse models.
+NESTML enables fast prototyping of new models using an easy to understand, yet powerful syntax, and combines
+this with high simulation performance through the automated generation of C++ code, suitable for use in NEST Simulator.
+
+NESTML combines:
+
+* fast prototyping
+* an easy to understand, yet powerful syntax;
+* a flexible processing toolchain, written in Python;
+* good simulation performance by means of code generation (C++ for NEST Simulator).
+
+.. seealso::
+
+  See the :doc:`NESTML docs for installation details <nestml:index>`
+
+.. note::
+
+  NESTML is also available as part of NEST's official :ref:`docker image <docker>`
+
+
+
+Model naming
+------------
+
+Neuron models
+~~~~~~~~~~~~~
+
+Neuron model names in NEST combine abbreviations that describe the dynamics and synapse specifications for that model.
+They may also include author's name of a model based on a specific paper.
+
+Example neuron model name
+
+``iaf_cond_beta``
+
+    an implementation of a spiking neuron using integrate and fire dynamics with
+    conductance-based synapses. Incoming spike events induce a postsynaptic change
+    of conductance modelled by a beta function.
+
+Example neuron model name based on specific paper
+
+``hh_cond_exp_traub``
+
+
+    a modified version of the Hodgkin Huxley neuron model based on Traub and Miles (1991)
+
+Synapse models
+~~~~~~~~~~~~~~
+
+Synapse models include the word synapse as last word in the model name.
+
+Synapse models may begin with author name (e.g., ``clopath_synapsae``) or process (e.g., ``stdp_synase``).
+
+Devices
+~~~~~~~
+
+A device name should represent its physical counterpart - like a multimeter is ``multimeter``.  In general, the term ``recorder`` is used for devices
+that store or generate output (e.g., spike times or synaptic strengths over time). The term  ``generator`` is used for devices that provide input into the simulation.
+
 
-* Discover :doc:`all the models in our directory <index>`
+.. seealso::
 
-Need to create your own?
+  See our glossary section on :ref:`common abbreviations used for model terms <model_terms>`. It includes alternative terms commonly used in the literatue.
 
-* Check out :doc:`NESTML <nestml:index>`, a domain-specific language supporting neuron and synapse models with a code generation backend that generates model code in C++ for NEST.

doc/htmldoc/ref_material/glossary.rst

@@ -5,59 +5,13 @@
 Glossary
 ========
 
+.. _units_measure:
+
+Units of measure
+---------------
 .. glossary::
  :sorted:
 
- iaf
-   Integrate and fire.
-
- gif
-   Generalized integrate and fire.
-
- cond
-   Conductance-based.
-
- psc
-   Post-synaptic current (current-based).
-
- hh
-   Hodgkin huxley.
-
- rng
-   Random number generator.
-
- wfr
-   Waveform relaxation method.
-
- aeif
-   Adaptive exponential integrate and fire.
-
- ht
-   Hill and tononi.
-
- pp
-   Point process.
-
- in
-   Inhibitory.
-
- ex
-   Excitatory.
-
- MAM
-   Multi-area model.
-
- mpi
-   Message passing interface.
-
- stdp
-   Spike-timing dependent plasticity synapse.
-
- st
-   Short term plasticity.
-
- vp
-   Virtual process.
 
  time
    Milliseconds (ms).
@@ -134,6 +88,90 @@ Glossary
  E_K
    Potassium reversal potential in Millivolts (mV).
 
+.. _model_terms:
+
+Terms for models in NEST
+------------------------
+
+.. glossary::
+ :sorted:
+
+ iaf
+   Integrate and fire. Also known in other sources as `IF`.
+
+ gif
+   Generalized integrate and fire. From Gersnter lab.  Also known in other sources as `spike response model (SRM)`.
+
+ glif
+   Generalized leaky integrate and fire. From Allen institute.
+
+ cond
+   Conductance-based. Also known in other sources as `COBA`.
+
+ psc
+   Post-synaptic current (current-based). Also known in other sources as `CUBA`.
+
+ hh
+   Hodgkin Huxley.
+
+ aeif
+   Adaptive exponential integrate and fire. Also known in other sources as `AdEx`.
+
+ ht
+   Hill and Tononi.
+
+ pp
+   Point process.
+
+ in
+   Inhibitory.
+
+ ex
+   Excitatory.
+
+ stdp
+   Spike-timing dependent plasticity synapse.
+
+ st
+   Short term plasticity.
+
+ psp
+   Post-synaptic potential.
+
+ sfa
+   Spike-frequency adaptation.
+
+ cm
+   compartmental model.
+
+Other abbreviations
+-------------------
+
+.. glossary::
+ :sorted:
+
+
+ rng
+   Random number generator.
+
+ wfr
+   Waveform relaxation method.
+
+ MAM
+   Multi-area model.
+
+ mpi
+   Message passing interface.
+
+ vp
+   Virtual process.
+
+Commonly used terms in NEST
+----------------------------
+
+.. glossary::
+ :sorted:
+
  subthreshold dynamics
    Non-spiking backgound activity of the synapses.
 
@@ -196,9 +234,6 @@ Glossary
  Gaussian white noise
    A random process with a mean of zero.
 
- sfa
-   Spike-frequency adaptation.
-
  point neuron
    A simple neuron model where its soma along with the membrane potential dynamics are modeled as a resistance–capacitance circuit.
 
@@ -238,12 +273,9 @@ Glossary
  renewal process
    Spike-time statistical analysis.
 
-  spike-frequency adaptation
+ spike-frequency adaptation
    After stimulation, neurons show a reduction in the firing frequency of their spike response following an initial increase.
 
- GIF
-   Generalized integrate-and-fire model.
-
  coefficient of variation
    Standard deviation divided by the mean.
 
@@ -256,12 +288,6 @@ Glossary
  soma
    Cell body of the neuron.
 
- psp
-   Post-synaptic potential.
-
- PSC
-   Post-synatpic current.
-
  absolute refractory
    An interval after a neuron fires a spike to prevent it from firing a spike again.
 

doc/htmldoc/static/css/custom.css

@@ -130,7 +130,6 @@ div.sd-card-title.sd-font-weight-bold.sd-d-flex-row.docutils a.reference.interna
 }
 
 .md-typeset .admonition {
-  background-color: var(--nest-blue);
   border-left: .2rem solid var(--nest-blue);
   border-radius: 5px;
 }

doc/htmldoc/understand_index.rst

@@ -45,7 +45,7 @@ Here you can dive into various topics about NEST.
 
    .. grid-item-card:: |math| Models in NEST
        :class-title: sd-d-flex-row sd-align-minor-center
-       :link:  models_contents
+       :link:  modelsmain
        :link-type: ref
 
 .. grid:: 1 1 2 3
@@ -102,7 +102,7 @@ Here you can dive into various topics about NEST.
    Synapses and connections <synapses/index>
    Devices  <devices/index>
    Spatially-structured networks <networks/spatially_structured_networks>
-   NEST models <models/index>
+   NEST models <models/models-main>
    Simulation behavior <nest_behavior/running_simulations>
    Randomness in NEST <nest_behavior/random_numbers>
    Built-in timers <nest_behavior/built-in_timers>