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

@@ -29,8 +29,16 @@ Install NEST
 
        I'm a developer who wants to :ref:`do development in NEST <dev_install>`
 
+|
+
+Install NESTML + NEST
+---------------------
+
+|nestml| I'm a user who wants to :ref:`create or customize models <nestml>`
+
 ----
 
+
 If installation didn't work, see the :ref:`troubleshooting section <troubleshooting>`.
 
 

doc/htmldoc/installation/nestml.rst

@@ -0,0 +1,27 @@
+.. _nestml:
+
+Install NESTML
+--------------
+
+
+Docker
+~~~~~~
+
+NESTML is available as part of NEST's official :ref:`docker image <docker>`
+
+
+pip
+~~~
+
+You can also install NESTML with pip. 
+Make sure it's installed in the same environment as NEST:
+
+
+.. code-block:: bash
+
+   pip install --pre nestml
+
+.. note::
+
+   Vist the :doc:`installation page for NESTML <nestml:installation>`
+

doc/htmldoc/models/models-main.rst

@@ -1,12 +1,141 @@
+.. _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::
+
+  :ref:`Install NESTML with NEST <nestml>`
+
+
+
+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 counter point - like a multimeter is ``multimeter``.  In general, the term ``recorder`` is used for devices
+that store or generate output. The term  ``generator`` is used for devices that provide input into the simulation.
+
+
+Table of model terms
+~~~~~~~~~~~~~~~~~~~~~
+
+The following table provides the NEST term used for a specific descriptor of a model along with commonly used alternative terms you may find in the literature.
+Additional terms may be used to help differentiate models not included in the list below.
+See the the :doc:`model directory <index>` to access the full description of each model.
+
+.. list-table:: Common model terms
+   :widths: 50 25 25
+   :header-rows: 1
+
+   * - Model description
+     - NEST term
+     - Alternative terms
+   * - Integrate and fire
+     - iaf
+     - IF
+   * - Adaptive exponential integrate and fire
+     - aeif
+     - AdEx
+   * - Hodgkin Huxley
+     - hh
+     -
+   * - Generalized integrate and fire (Spike response model)
+     - gif
+     - SRM
+   * - Generalized leaky integrate and fire
+     - glif
+     -
+   * -
+     - amat / mat
+     -
+   * - Conductance based
+     - cond
+     - COBA
+   * - Current based
+     - psc
+     - CUBA
+   * - Hill Tononi
+     - ht
+     -
+   * - Point process
+     - pp
+     -
+   * - spike timing dependent plasticity
+     - stdp
+     -
+   * - Compartmental model
+     - cm
+     -
+   * - precise spike timing
+     - ps
+     -
 
-* Discover :doc:`all the models in our directory <index>`
 
-Need to create your own?
 
-* 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/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>