Merge pull request #3067 from jessica-mitchell/doc-installpage

Improve doc install pages

doc/htmldoc/installation/cmake_options.rst

@@ -40,6 +40,29 @@ NEST allows for several configuration options for custom builds:
 
 .. _modelset_config:
 
+Minimal configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+
+NEST can be compiled without any external packages; such a configuration may be useful for initial porting to a new supercomputer.
+However, this implies several restrictions:
+
+- Some neuron and synapse models will not be available, as they depend on ODE solvers from the GNU Scientific Library.
+- The Python extension will not be available
+- Multi-threading and parallel computing facilities will be disabled.
+
+To configure NEST for compilation without external packages, use the following  command::
+
+    cmake -DCMAKE_INSTALL_PREFIX:PATH=<nest_install_dir> \
+          -Dwith-python=OFF \
+          -Dwith-gsl=OFF \
+          -Dwith-readline=OFF \
+          -Dwith-ltdl=OFF \
+          -Dwith-openmp=OFF \
+          </path/to/nest/source>
+
+See the :ref:`CMake Options <cmake_options>` to  further adjust settings for your system.
+
 Select built-in models
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -104,7 +127,7 @@ Build documentation
 If either documentation build is toggled to `ON`, you can then run ``make docs`` if you only want to
 build the docs.
 
-See also the :ref:`documentation workflow <doc_workflow>` for user and developer docs.
+See also the :ref:`documentation workflow <doc_workflow>` for user facing and technical docs.
 
 
 External libraries
@@ -180,7 +203,7 @@ Generic build configuration
 | ``-Dwith-intel-compiler-flags=[OFF|<list;of;flags>]``| User defined flags for the Intel compiler                        |
 |                                                      | [default='-fp-model strict']. Separate multiple flags by ';'.    |
 +------------------------------------------------------+------------------------------------------------------------------+
-| ``-Dwith-cpp-std=[<C++ standard>]``                  | C++ standard to use for compilation [default='c++17'].           |
+| ``-Dwith-cpp-std=[<C++ standard>]``                  | C++ standard to use for compilation [default='c++11'].           |
 +------------------------------------------------------+------------------------------------------------------------------+
 | ``-Dwith-libraries=[OFF|<list;of;libraries>]``       | Link additional libraries [default=OFF]. Give full path. Separate|
 |                                                      | multiple libraries by ';'.                                       |

doc/htmldoc/installation/docker.rst

@@ -1,9 +1,10 @@
 .. _docker:
 
 Docker |macos| |linux|
-----------------------
+======================
 
 Docker provides an isolated container to run applications.
+Our docker image for NEST also includes NESTML.
 
 1. If you do not have Docker installed, follow the Docker
    installation instructions for your system here:
@@ -25,7 +26,7 @@ Docker provides an isolated container to run applications.
 
 
 Usage
-
+-----
 
 You can use the docker images directly out of https://hub.docker.com/r/nest/nest-simulator
 like this:
@@ -37,20 +38,24 @@ like this:
 ``<TAG>`` can be a version of NEST ``2.20.2`` or later. Alternatively, you can use ``dev`` for the
 development branch (master).
 
+.. _docker_compose:
+
 NEST 3.2 and later
-^^^^^^^^^^^^^^^^^^
+------------------
 
-As of NEST 3.2, you can use the docker-compose feature.
+As of NEST 3.2, you can use the docker-compose feature. This feature provides options to run additional applications along with NEST.
 
-To use 'docker-compose' you need the definition file from the git repository. Download it:
+To use ``docker-compose`` you need the definition file from the git repository.
+Download it:
 
 .. code-block:: bash
 
     wget https://raw.githubusercontent.com/nest/nest-docker/master/docker-compose.yml
 
 You can then run ``docker-compose up`` with one of the following options:
 
-- NEST server
+NEST server
+~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -66,7 +71,10 @@ or
 Starts the NEST API server container and opens the corresponding port 52425. Test it with `curl localhost:52425/api`.
 See the :ref:`nest_server` documentation for more details.
 
-- NEST desktop
+.. _docker_desktop:
+
+NEST Desktop
+~~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -86,7 +94,8 @@ Open NEST Desktop in the web browser using the following http link: `http://loca
 
 Visit the :doc:`NEST Desktop <desktop:index>` documentation to learn more.
 
-- Jupyter notebook with NEST
+Jupyter notebook with NEST
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -103,7 +112,8 @@ Starts a notebook server with pre-installed NEST. The corresponding URL is displ
 d paste into your browser.
 
 
-- Jupyter lab with NEST
+Jupyter lab with NEST
+~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: bash
 
@@ -119,12 +129,13 @@ or
 Starts a Jupyter lab server with pre-installed NEST. The corresponding URL is displayed in the console.
 Copy and paste the URL into your browser.
 
+Remove container
+----------------
 
-
-To stop and delete running containers use `docker-compose down`.
+To stop and delete running containers use ``docker-compose down``.
 
 To run NEST 2.20.2
-^^^^^^^^^^^^^^^^^^
+------------------
 
 Jupyter notebook with NEST 2.20.2:
 
@@ -134,7 +145,7 @@ Jupyter notebook with NEST 2.20.2:
                -p 8080:8080 nest/nest-simulator:2.20.2
 
 NEST dev
-^^^^^^^^
+--------
 
 If you want to use the compose configuration for the ``dev`` NEST version, you can use the following file option:
 
@@ -143,10 +154,16 @@ If you want to use the compose configuration for the ``dev`` NEST version, you c
     wget https://raw.githubusercontent.com/nest/nest-docker/master/docker-compose-dev.yml
     docker-compose -f docker-compose-dev.yml up nest-notebook
 
+You can specify the container mode (nest-noteobook, nest-desktop, nest-server, or nest-jupyterlab)
+This will download the docker image with the pre-installed
+NEST master from https://hub.docker.com/r/nest/nest-simulator and start it.
+After booting, a URL is presented. Click on it or copy it to your browser.
+
+
 .. _docker_win:
 
 Run NEST on Windows |windows|
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
 
 .. important::
 

doc/htmldoc/installation/index.rst

@@ -3,40 +3,66 @@
 Install NEST
 ============
 
-.. grid:: 1 1 2 2
 
-   .. grid-item-card::  |user| Install pre-built NEST package
-       :class-title: sd-d-flex-row sd-align-minor-center
+.. grid:: 2
+   :gutter: 1
 
-       I'm a user who wants to :ref:`install NEST on my computer <user_install>`
+   .. grid-item-card:: |user|  Install a pre-built NEST package using
+      :class-title: sd-d-flex-row sd-align-minor-center
+      :columns: 4
 
+      * :ref:`Docker (cross-platform) <docker>`
+        (Includes NESTML)
+      * :ref:`conda-forge (Linux/macOS) <conda_forge_install>`
+      * :ref:`Ubuntu PPA (Linux) <ubuntu_install>`
+      * :ref:`Homebrew (macOS) <macos_install>`
+      * :ref:`Options for Windows users <windows_install>`
 
-   .. grid-item-card:: |teacher| Install NEST for a class or workshop
-       :class-title: sd-d-flex-row sd-align-minor-center
 
-       I'm a lecturer who wants to :ref:`use NEST to teach <lecturer>`
+   .. grid-item-card:: |dev| Source install
+      :class-title: sd-d-flex-row sd-align-minor-center
+      :columns: 4
 
+      If you want to do development with NEST
 
-.. grid:: 1 1 2 2
+      * :ref:`dev_install`
 
-    .. grid-item-card:: |admin| Install NEST for supercomputers and clusters
-       :class-title: sd-d-flex-row sd-align-minor-center
+Install related tools
+~~~~~~~~~~~~~~~~~~~~~
 
-       I'm an admin or user who wants to :ref:`run NEST on HPC <admin_install>`
+.. grid:: 2
+   :gutter: 1
 
-    .. grid-item-card:: |dev| Install NEST from source
-       :class-title: sd-d-flex-row sd-align-minor-center
+   .. grid-item-card:: |desktop|
+      :class-title: sd-d-flex-row sd-align-minor-center
+      :columns: 4
 
-       I'm a developer who wants to :ref:`do development in NEST <dev_install>`
+      A graphical user interface, ideal for learning and teaching concepts
+      regarding neural networks in classrooms and workshops.
 
-.. grid:: 1 1 2 2
+      * :doc:`NEST Desktop documentation <desktop:index>` :octicon:`link-external`
 
-    .. grid-item-card:: |nestml| Install NEST with NESTML
-       :class-title: sd-d-flex-row sd-align-minor-center
+      * :ref:`Install docker container with NEST + NEST Desktop <docker_compose>`
 
-       I'm a user who wants to :doc:`create or customize models <nestml:installation>`.
+   .. grid-item-card:: |nestml|
+      :class-title: sd-d-flex-row sd-align-minor-center
+      :columns: 4
 
-|
+      Install the NEST modeling language to create and customize models
+
+
+      * :doc:`NESTML documentation <nestml:index>` :octicon:`link-external`
+
+      * :ref:`Install docker container for NEST + NESTML <docker>`
+
+
+   .. grid-item-card:: |hpc| Configure HPC systems
+      :class-title: sd-d-flex-row sd-align-minor-center
+      :columns: 4
+
+      Find out how to set up and optimize HPC systems for NEST
+
+      * :ref:`optimize_performance`
 
 
 
@@ -51,7 +77,6 @@ If installation didn't work, see the :ref:`troubleshooting section <troubleshoot
    :glob:
 
    mac_install
-   hpc_install
    livemedia
    cmake_options
    *
@@ -60,5 +85,6 @@ 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%
+.. |desktop| image:: ../static/img/nestdesktop022023.svg
+.. |nestml| image:: ../static/img/nestml022023.svg
+.. |hpc| image:: ../static/img/hpc_orange128.svg

doc/htmldoc/installation/noenv_install.rst

@@ -4,7 +4,7 @@ Install from source without a virtual environment
 =================================================
 
 The following are the basic steps to compile and install NEST from source code. See the
-:ref:`CMake Options <cmake_options>` or the :ref:`High Performance Computing <hpc_install>` instructions to
+:ref:`CMake Options <cmake_options>` instructions to
 further adjust settings for your system.
 
 * If not already installed on your system, the following packages are recommended.
@@ -95,6 +95,3 @@ sourcing the script:
 .. code-block:: sh
 
    source <nest_install_dir>/bin/nest_vars.sh
-
-
-

doc/htmldoc/installation/user.rst

@@ -32,6 +32,8 @@ We have live media (.ova) if you want to run NEST in a virtual machine.
 Linux |linux|
 -------------
 
+.. _ubuntu_install:
+
 Ubuntu
 ~~~~~~
 
@@ -66,6 +68,8 @@ Or install NEST with `NESTML <https://nestml.readthedocs.io/en/latest/index.html
 --------
 
 
+.. _macos_install:
+
 macOS |macos|
 -------------
 
@@ -79,6 +83,7 @@ macOS |macos|
 
 --------
 
+.. _windows_install:
 
 Options for Windows users |windows|
 ------------------------------------