Merge pull request #2288 from jessica-mitchell/install_page

Update installation pages for Read the docs

doc/userdoc/installation/admin.rst

@@ -0,0 +1,26 @@
+.. _admin_install:
+
+Administrator installation instructions
+---------------------------------------
+
+If you need to deploy NEST on a machine
+
+
+*  Check out our guides to :ref:`optimizing NEST for HPC systems <hpc_index>`
+
+Configure HPC systems
+~~~~~~~~~~~~~~~~~~~~~
+
+Here are some :ref:`configuration options <hpc_install>` that may be useful on supercomputers and large clusters.
+
+Docker install
+~~~~~~~~~~~~~~
+
+Check out the :ref:`docker installation instructions <docker>`.
+
+
+See the `nest-docker README <https://github.com/nest/nest-docker>`_ to find out more.
+
+
+
+

doc/userdoc/installation/conda_forge.rst

@@ -0,0 +1,53 @@
+.. _conda_forge_install:
+
+Conda forge install
+===================
+
+1. To keep your conda setup tidy, we recommend that you install NEST into
+   a separate `conda environment <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_
+   together with Python packages that you will use when working with NEST;
+   see also our :ref:`conda_tips`.
+
+   To install the latest version of NEST in a new environment called ``ENVNAME``, just run
+
+   .. code-block:: sh
+
+      conda create --name ENVNAME -c conda-forge nest-simulator
+
+   To install additional packages into the environment, just list them together with ``nest-simulator``.
+
+   .. code-block:: sh
+
+      conda create --name ENVNAME -c conda-forge nest-simulator jupyterlab seaborn
+
+#. To see all NEST versions available via conda, either run
+
+   .. code-block:: sh
+
+      conda search -c conda-forge nest-simulator
+
+   or browse the `conda forge file list
+   <https://anaconda.org/conda-forge/nest-simulator/files>`_ (note
+   there are multiple pages). To install, e.g., NEST 2.18.0, run
+
+   .. code-block:: sh
+
+      conda create --name nest_2_18_0 -c conda-forge nest-simulator=2.18.0=*
+
+   The syntax for this install follows the pattern: ``nest-simulator=<version>=<build_string>``.
+
+#. Activate your environment:
+
+   .. code-block:: sh
+
+      conda activate ENVNAME
+
+#. Note the following:
+
+   - We currently provide NEST with thread-based parallelization on conda. This should suffice for most
+     uses on personal computers.
+   - Until dedicated conda builds for Apple's M1 chip (arm64) become available, you should expect relatively
+     poor performance on computers with the M1 chip. You need to :ref:`build NEST yourself <mac_install>` on
+     M1 systems for good performance.
+
+

doc/userdoc/installation/condaenv_install.rst

@@ -0,0 +1,57 @@
+.. _condaenv:
+
+Install from source in a conda environment
+==========================================
+
+* Create a conda environment from the `environment.yml <https://github.com/nest/nest-simulator/blob/master/environment.yml>`_ file.
+  We recommend specifying a dedicated location (``-p <path/to/conda/env>``) for your environment.
+  See the `conda documentation <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#specifying-a-location-for-an-environment>`_
+  on using a custom location rather than the default envs folder.
+
+.. code-block:: sh
+
+    conda env create -f nest-simulator/environment.yml --p <path/to/conda/env>
+    conda activate <path/to/conda/env>
+
+* Create a build directory:
+
+.. code-block:: sh
+
+    mkdir build_dir
+
+* Change to the build directory:
+
+.. code-block:: sh
+
+    cd build_dir
+
+* Configure NEST. Add the cmake option ``-CDMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX`` to link nest to your active conda environment.
+  You may need additional ``cmake`` options (see :ref:`cmake_options`).
+
+.. code-block:: sh
+
+   cmake -DCMAKE_INSTALL_PREFIX:PATH=$CONDA_PREFIX </path/to/NEST/src>
+
+* Compile and install NEST:
+
+.. code-block:: sh
+
+    make
+    make install
+    make installcheck
+
+For your convenience, a shell script setting all required environment variables is provided in
+``<nest_install_dir>/bin/nest_vars.sh``. Setting the environment variables in your active shell session requires
+sourcing the script:
+
+.. code-block:: sh
+
+   source <nest_install_dir>/bin/nest_vars.sh
+
+
+
+.. note::
+
+   To build the developer or user documentation see :ref:`doc_workflow`
+
+

doc/userdoc/installation/developer.rst

@@ -0,0 +1,54 @@
+.. _dev_install:
+
+Install NEST from source
+=========================
+
+
+.. note::
+
+    Please see our :ref:`development workflows and guidelines <developer_space>`, if you need
+    a refresher in git or need to review the coding or documentation guidelines.
+
+
+
+* Clone nest-simulator from Github `<https://github.com/nest/nest-simulator>`_:
+
+.. code-block:: sh
+
+   git clone git@github.com:<your-username>/nest-simulator.git
+
+
+* or download the tarball `here <https://github.com/nest/nest-simulator/releases>`_ and unpack it:
+
+.. code-block:: sh
+
+    tar -xzvf nest-simulator-x.y.tar.gz
+
+
+
+We have provided an `environment.yml <https://github.com/nest/nest-simulator/blob/master/environment.yml>`_
+file that contains all possible packages needed for NEST development.
+See our instructions for installing NEST from source in a :ref:`conda environment <condaenv>`
+
+OR
+
+If you want to install NEST without any environment, see the :ref:`instructions here <noenv>`.
+
+What gets installed where
+-------------------------
+
+By default, everything will be installed to the subdirectories ``<nest_install_dir>/{bin,lib,share}``, where
+``/install/path`` is the install path given to ``cmake``:
+
+- Executables ``<nest_install_dir>/bin``
+- Dynamic libraries ``<nest_install_dir>/lib/``
+- SLI libraries ``<nest_install_dir>/share/nest/sli``
+- SLI documentation ``<nest_install_dir>/share/doc/nest``
+- Examples ``<nest_install_dir>/share/doc/nest/examples``
+- PyNEST ``<nest_install_dir>/lib/pythonX.Y/site-packages/nest``
+- PyNEST examples ``<nest_install_dir>/share/doc/nest/examples/pynest``
+
+If you want to run the ``nest`` executable or use the ``nest`` Python module without providing explicit paths, you
+have to add the installation directory to your search paths.
+
+