Add new options for installation and improve instructions for NEST

doc/_static/css/custom.css

@@ -2,6 +2,13 @@ t.rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
     color: #f63;
 }
 
+p {
+    margin-bottom: 12px;
+}
+
+.wy-nav-content {
+    max-width: 950px;
+}
 
 .wy-side-nav-search>a, .wy-side-nav-search .wy-dropdown>a {
    content: url(../../_static/img/nest_logo.png);
@@ -114,6 +121,27 @@ code.descclassname {
 
 }
 
+.wy-plain-list-disc, .rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {
+    margin-bottom: 12px;
+}
+
+.rst-content dl:not(.docutils) dt {
+    background: #ff663336;
+    border-top: solid 3px #ff6633;
+    color: black;
+}
+
+.rst-content .pull-quote {
+    background: #f0f3f3;
+    padding: 0.5em;
+    border: 1px solid #ff6633;
+    border-radius: 5px;
+}
+
+.rst-content kbd {
+    background-color: lightgray;
+}
+
 .rst-content .admonition {
     background: #e0e0e0;
 
@@ -129,4 +157,3 @@ code.descclassname {
    .wy-table-responsive {
       overflow: visible !important;
    }
-}

doc/conf.py

@@ -85,6 +85,7 @@ def __getattr__(cls, name):
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'breathe',
+    'sphinx_tabs.tabs'
 ]
 
 breathe_projects = {"EXTRACT_MODELS": "./xml/"}

doc/contents.rst

@@ -12,6 +12,7 @@ Table of Contents
    download
    installation/index
    getting_started
+   troubleshooting
    tutorials/index
    models/index
    examples/index

doc/download.rst

@@ -1,65 +1,86 @@
 Download NEST
 ===================
 
-NEST is available under the :doc:`GNU General Public License 2 or later <license>`. This means that you can
 
--  use NEST for your research,
--  modify and improve NEST according to your needs,
--  distribute NEST to others under the same license.
+.. pull-quote::
+
+   For standard situations where you just want to use but not modify
+   NEST, you don't have to download the source code.
+
+   Distribution packages ease the installation on Debian/Ubuntu,
+   Fedora, macOS and Conda.
+
+   See our :doc:`installation instructions <installation/index>` to
+   find the right option for you.
 
+
+Here you'll find the lastest versions of the source code and Live Media for download.
 If you use NEST for your project, don't forget to :doc:`cite NEST <citing-nest>`!
 
-Download the current version of NEST here:
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`Current Release NEST 2.16.0 <https://github.com/nest/nest-simulator/archive/v2.16.0.tar.gz>`_
-````````````````````````````````````````````````````````````````````````````````````````````````````
-`Release Notes <https://github.com/nest/nest-simulator/releases/tag/v2.16.0>`_
+Download NEST source code
+--------------------------
+
+* Get the `source code of the latest release <https://github.com/nest/nest-simulator/archive/v2.18.0.tar.gz>`_.
+
+
+* Follow the installation instructions for :doc:`Linux <installation/linux_install>` or :ref:`macOS <mac_manual>`.
+
+.. seealso::
 
+  Previous versions and associated release notes can be found at
+  https://github.com/nest/nest-simulator/releases/
 
-`Latest developer version <https://github.com/nest/nest-simulator>`_
+.. _download_livemedia:
 
-Download the NEST Live Media for Virtual Machines
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Download the NEST live media for virtual machines
+--------------------------------------------------
 
 Live media is available in the OVA format, and is suitable, for example, for importing into VirtualBox.
 If you run **Windows**, this is the option for you OR if you just want to run NEST without installing it on your computer.
+After downloading the virtual machine, check out the :doc:`install instructions for Live Media <installation/livemedia>`.
 
-`NEST Live Media 2.14.0 <https://www.nest-simulator.org/downloads/gplreleases/nest-live.ova>`_ (OVA, 2.5G)
+* `NEST Live Media 2.18.0 <https://nest-simulator.org/downloads/gplreleases/lubuntu-18.04_nest-2.18.0.ova>`_
 
-`Checksum 2.14.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.14.0.ova.sha512sum>`_
+  `Checksum 2.18.0 <https://nest-simulator.org/downloads/gplreleases/lubuntu-18.04_nest-2.18.0.ova.sha512sum>`_
 
-See the :doc:`install instructions for Live Media <installation/livemedia>`
 
+* `NEST live media 2.16.0 <https://nest-simulator.org/downloads/gplreleases/lubuntu-18.04_nest-2.16.0.ova>`_
 
-Previous Releases
-~~~~~~~~~~~~~~~~~~~
-We continuously aim to improve NEST and implement features and fix bugs with every new version;
-thus, we strongly encourage our users to use the **most recent version of NEST**. However,
-if you do need an older version you can find `all NEST releases here <https://github.com/nest/nest-simulator/releases/>`_.
+  `Checksum 2.16.0 <https://nest-simulator.org/downloads/gplreleases/lubuntu-18.04_nest-2.16.0.ova.sha512sum>`_
+
+
+Previous releases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We continuously aim to improve NEST, implement features, and fix bugs with every new version;
+thus, we encourage our users to use the **most recent version of NEST**.
 
 **Older Versions of Live Media**
 
-- Ubuntu 16.04 Live Media with NEST 2.12.0
+- `NEST Live Media 2.14.0 <https://www.nest-simulator.org/downloads/gplreleases/nest-live.ova>`_ (OVA, 2.5G)
+
+   `Checksum 2.14.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.14.0.ova.sha512sum>`_
+
+- `Download 2.12.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.12.0.ova>`_ (OVA, 3.2G)
 
-    - `Download 2.12.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.12.0.ova>`_
-      (OVA, 3.2G)
+   `Checksum 2.12.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.12.0.ova.sha512sum>`_
 
-    - `Checksum 2.12.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.12.0.ova.sha512sum>`_
-      (sha512sum)
 
--  Ubuntu 16.04 Live Media with NEST 2.10.0
+-  `Download 2.10.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.10.0.ova>`_
+   (OVA, ~3.7G)
 
-   -  `Download 2.10.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.10.0.ova>`_
-      (OVA, ~3.7G)
+    `Checksum 2.10.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.10.0.ova.sha512sum>`_
 
-   -  `Checksum 2.10.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-16.04_nest-2.10.0.ova.sha512sum>`_
-      (sha512sum)
+-  `Download 2.8.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova>`_
+   (OVA, ~2.5G)
 
-- Ubuntu 15.10 Live Media with NEST 2.8.0
+    `Checksum 2.8.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova.sha512sum>`_
 
-   -  `Download 2.8.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova>`_
-      (OVA, ~2.5G)
+----
 
-   -  `Checksum 2.8.0 <https://www.nest-simulator.org/downloads/gplreleases/lubuntu-15.10_nest-2.8.0.ova.sha512sum>`_
-      (sha512sum)
+NEST is available under the :doc:`GNU General Public License 2 or later <license>`. This means that you can
+
+-  use NEST for your research,
+-  modify and improve NEST according to your needs,
+-  distribute NEST to others under the same license.

doc/getting_help.rst

@@ -5,7 +5,7 @@ Getting Help
 Have a specific question or problem with NEST?
 ------------------------------------------------
 
-* Check out the :doc:`FAQs <faqs/index>` for common issues.
+* Check out the :doc:`troubleshooting section <troubleshooting>` for common issues.
 
 If your question is not on there, ask our :doc:`Mailing List <community>`.
 

doc/getting_started.rst

@@ -1,131 +1,91 @@
 Getting Started
-================
+===============
 
-A quick overview of simulating neural networks
-------------------------------------------------
+Have you already :doc:`installed NEST <installation/index>`?
 
+Then let's look at how to create a neural network simulation!
+
+NEST is a command line tool for simulating neural networks.
 A NEST simulation tries to follow the logic of an electrophysiological
 experiment - the difference being it takes place inside the computer
 rather than in the physical world.
 
-In NEST, the neural system is a collection of **nodes** and their `Connections`_.
-Nodes correspond to ``neurons`` and ``devices`` and connections by ``synapses``.
-Different neuron and synapse models can coexist in the same network.
-
-To measure or observe the network activity, you can define
-so-called `Devices`_ that represent the various instruments (for measuring and
-stimulating) found in an experiment. These devices write their data either to
-memory or to file.
+You can use NEST interactively from the Python prompt, from within
+IPython or in a Jupyter Notebook.  The latter is helpful when you are
+exploring PyNEST, trying to learn a new functionality or debugging a
+routine.
 
-The network and its configuration are defined at the level
-of the simulation language interpreter (SLI) as well as the PyNEST level.
+How does it work?
+-------------------
 
-Check out our :doc:`PyNEST tutorial <tutorials/index>`,
-which will explain how to build your first neural network simulation in NEST.
+Let's start with a basic script to simulate a simple neural network.
 
+* Run Python or a Jupyter Notebook and try out this example simulation in NEST:
 
-.. sidebar:: See Also
+Import required packages:
 
-    * :doc:`List of Models in NEST <models/index>`
-    * :doc:`Create your own model <models/create_model>`
-    * :doc:`Examples of Network Models <examples/index>`
+.. code-block:: python
 
+   import nest
+   import nest.voltage_trace
+   nest.ResetKernel()
 
-How do I use NEST?
--------------------
-As the experimenter, you need a clear idea of *what* you want to learn from the experiment.
-In the context of a network `Simulation`_, this means that you have to know
-*which input* you want to give to your network and *which output* you're interested in.
+Create the neuron models you want to simulate:
 
-You can use NEST either with Python (PyNEST) or as a stand alone application (
-``nest``).
-PyNEST provides a :doc:`set of commands <ref_material/index>` to the Python interpreter which give you
-access to NEST's simulation kernel. With these commands, you describe and run
-your network simulation.
+.. code-block:: python
 
-A basic network setup in PyNEST
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+   neuron = nest.Create('iaf_psc_exp')
 
-You can use PyNEST interactively from the Python prompt or from within ipython.
-This is very helpful when you are exploring PyNEST, trying to learn a new
-functionality or debugging a routine. Once out of the exploratory mode, you will
-find it saves a lot of time to write your simulations in text files. These can
-in turn be run from the command line or from the Python or ipython prompt.
+Create the devices to stimulate or observe the neurons in the simulation:
 
-Fundamentally, you can build a basic network with the following functions::
+.. code-block:: python
 
-    # Create the models you want to simulate
-    neuron = nest.Create("model_name")
+   spikegenerator = nest.Create('spike_generator')
+   voltmeter = nest.Create('voltmeter')
 
-    # Create the device to stimulate or measure the simulation
-    device = nest.Create("device_name")
+Modify properties of the device:
 
-    # Modify properties of the neuron and device
-    nest.SetStatus(neuron, {"key" : value})
-    nest.SetStatus(device, {"key" : value})
+.. code-block:: python
 
-    # Tell NEST how they are connected to each other (synapse properties can be
-    # added here)
-    nest.Connect(device, neuron, syn_spec={"key": [value1, value2]})
+    nest.SetStatus(spikegenerator, {'spike_times': [10.0, 50.0]})
 
-    # Simulate network providing a specific timeframe.
-    nest.Simulate(time_in_ms)
+Connect neurons to devices and specify synapse (connection) properties:
 
-NEST is extensible and new models for neurons, synapses, and devices can be
-added. You can find out how to :doc:`create your own model <models/create_model>`
-using NESTML and c++.
+.. code-block:: python
 
+   nest.Connect(spikegenerator, neuron, syn_spec={'weight': 1e3})
+   nest.Connect(voltmeter, neuron)
 
-Connections
-~~~~~~~~~~~~
+Simulate the network for the given time in miliseconds:
 
-Connections between nodes (neurons, devices or synapses) define possible channels for interactions between
-them. A connection between two nodes is established, using the command
-``Connect``.
+.. code-block:: python
 
-Each connection has two basic parameters, *weight* and *delay*. The weight
-determines the strength of the connection, the delay determines how long an
-event needs to travel from the sending to the receiving node. The delay must be
-a positive number greater or equal to the simulation stepsize and is given in
-ms.
+   nest.Simulate(100.0)
 
-Devices
-~~~~~~~~
+Display the voltage graph from the voltmeter:
 
-Devices are network nodes which provide input to the network or record its
-output. They encapsulate the stimulation and measurement process. If you want
-to extract certain information from a simulation, you need a device which is
-able to deliver this information. Likewise, if you want to send specific input
-to the network, you need a device which delivers this input.
+.. code-block:: python
 
-Devices have a built-in timer which controls the period they are active. Outside
-this interval, a device will remain silent. The timer can be configured using
-the command ``SetStatus``.
+   nest.voltage_trace.from_device(voltmeter)
+   nest.voltage_trace.show()
 
-Simulation
-~~~~~~~~~~~~~
+You should see the following image as the output:
 
-NEST simulations are time driven. The simulation time proceeds in discrete steps
-of size ``dt``, set using the property ``resolution`` of the root node. In each time
-slice, all nodes in the system are updated and pending events are delivered.
+.. image:: _static/img/output_getting_started.png
+   :align: center
 
-The simulation is run by calling the command ``Simulate(t)``, where ``t`` is the
-simulation time in milliseconds. See below for list of physical units in NEST.
+**And that's it! You have performed your first neuronal simulation in NEST!**
 
-Physical units in NEST
------------------------
 
--   time - ms
--   voltage - mV
--   capacitance - pF
--   current - pA
--   conductance - nS
--   Spike rates (e.g. poisson\_generator) - spikes/s
--   modulation frequencies (e.g. ac\_generator) - Hz
+Want to know more?
+------------------
 
-Next Steps
------------
+* Check out our :doc:`PyNEST tutorial <tutorials/index>`, which
+  provides full explanations on how to build your first neural network
+  simulation in NEST.
 
-* :doc:`Download <download>` and :doc:`Install NEST <installation/index>`
-* Follow the :doc:`PyNEST tutorial <tutorials/index>` and simulate a neural network
+* We have a large collection of :doc:`Example networks
+  <examples/index>` for you to explore.
 
+* Regularly used terms and default physical units in NEST are
+  explained in the :doc:`Glossary <glossary>`.