aiidateam · ramirezfranciscof · Nov 6, 2020 · Oct 20, 2020 · Oct 20, 2020 · Oct 21, 2020
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -47,7 +47,7 @@
 ]
 ipython_mplbackend = ''
 copybutton_selector = 'div:not(.no-copy)>div.highlight pre'
-copybutton_prompt_text = r'>>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
+copybutton_prompt_text = r'>>> |\.\.\. |(?:\(.*\) )?\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
 copybutton_prompt_is_regexp = True
 
 todo_include_todos = False

diff --git a/docs/source/howto/installation.rst b/docs/source/howto/installation.rst
@@ -157,7 +157,7 @@ Isolating multiple instances
 An AiiDA instance is defined as the installed source code plus the configuration folder that stores the configuration files with all the configured profiles.
 It is possible to run multiple AiiDA instances on a single machine, simply by isolating the code and configuration in a virtual environment.
 
-To isolate the code, simply create a virtual environment, e.g., with conda or venv, and then follow the instructions for :ref:`installation<intro:install:aiida-core>` after activation.
+To isolate the code, make sure to install AiiDA into a virtual environment, e.g., with conda or venv, as described :ref:`here <intro:get_started:setup>`.
 Whenever you activate this particular environment, you will be running the particular version of AiiDA (and all the plugins) that you installed specifically for it.
 
 This is separate from the configuration of AiiDA, which is stored in the configuration directory which is always named ``.aiida`` and by default is stored in the home directory.

diff --git a/docs/source/howto/ssh.rst b/docs/source/howto/ssh.rst
@@ -268,6 +268,6 @@ Using kerberos tokens
 If the remote machine requires authentication through a Kerberos token (that you need to obtain before using ssh), you typically need to
 
  * install ``libffi`` (``sudo apt-get install libffi-dev`` under Ubuntu)
- * install the ``ssh_kerberos`` extra during the installation of aiida-core (see :ref:`intro:install:aiida-core`).
+ * install the ``ssh_kerberos`` extra during the installation of aiida-core (see :ref:`intro:install:setup`).
 
 If you provide all necessary ``GSSAPI`` options in your ``~/.ssh/config`` file, ``verdi computer configure`` should already pick up the appropriate values for all the gss-related options.
diff --git a/docs/source/intro/get_started.rst b/docs/source/intro/get_started.rst
@@ -1,7 +1,7 @@
 .. _intro:get_started:
 
 ****************
-Getting Started
+Getting started
 ****************
 
 An AiiDA installation consists of three core components (plus any external codes you wish to run):
@@ -10,213 +10,86 @@ An AiiDA installation consists of three core components (plus any external codes
 * |PostgreSQL|: The service that manages the database that AiiDA uses to store data.
 * |RabbitMQ|: The message broker used for communication within AiiDA.
 
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   install_system
+   install_conda
+   run_docker
+
+.. _intro:install:setup:
+.. _intro:get_started:setup:
+
+Setup
+=====
+
 There are multiple routes to setting up a working AiiDA environment.
-These are shown below, followed by a recommended "quick-install" route on your local computer.
+Which of those is optimal depends on your environment and use case.
+If you are unsure, use the :ref:`system-wide installation <intro:get_started:system-wide-install>` method.
 
 .. panels::
    :body: bg-light
    :footer: bg-light border-0
 
-   :fa:`desktop,mr-1` **Direct (Bare Metal)**
-
-   *Install software directly into your local root directory.*
+   :fa:`desktop,mr-1` **System-wide installation**
 
-   The prerequisite software can be installed using most package managers, including: apt, Homebrew, MacPorts, Gentoo and Windows Subsystem for Linux.
+   .. link-button:: intro:get_started:system-wide-install
+      :type: ref
+      :text: Install all software directly on your workstation or laptop.
+      :classes: stretched-link btn-link
 
-   +++
-
-   :link-badge:`intro:install:prerequisites,Prerequisites install,ref,badge-primary text-white`
-   :link-badge:`intro:install:aiida-core,aiida-core install,ref,badge-primary text-white`
+   Install the prerequisite services using standard package managers (apt, homebrew, etc.) with administrative privileges.
 
    ---------------
 
-   :fa:`folder,mr-1` **Virtual Environment**
-
-   *Install software into an isolated directory on your machine.*
+   :fa:`folder,mr-1` **Installation into Conda environment**
 
-   Environment managers such as `Conda <https://docs.conda.io>`__, `pipenv <https://pipenv.pypa.io>`__  and `venv <https://docs.python.org/3/library/venv.html>`__ create isolated environments, allowing for installation of multiple versions of software on the same machine.
-   It is advised that you install ``aiida-core`` into one of these managed environments.
+   .. link-button:: intro:get_started:conda-install
+      :type: ref
+      :text: Install all software into an isolated conda environment.
+      :classes: stretched-link btn-link
 
-   +++
-
-   :link-badge:`intro:install:virtual_environments,Environments Tutorial,ref,badge-primary text-white`
-   :link-badge:`https://anaconda.org/conda-forge/aiida-core,aiida-core on Conda,url,badge-primary text-white`
+   This method does not require administrative privileges, but involves manual management of start-up and shut-down of services.
 
    ---------------
 
-   :fa:`cube,mr-1` **Containers**
-
-   *Use a pre-made image of all the required software.*
+   :fa:`cube,mr-1` **Run via docker container**
 
-   AiiDA maintains a `Docker <https://www.docker.com/>`__ image, which is particularly useful for learning and testing purposes.
-   It is a great way to quickly get started on the tutorials.
+   .. link-button:: intro:get_started:docker
+      :type: ref
+      :text: Run AiiDA and prerequisite services as a single docker container.
+      :classes: stretched-link btn-link
 
-   +++
-
-   :link-badge:`intro:install:docker,Docker Tutorial,ref,badge-primary text-white`
-   :link-badge:`https://hub.docker.com/r/aiidateam/aiida-core,aiida-core on DockerHub,url,badge-primary text-white`
+   Does not require the separate installation of prerequisite services.
+   Especially well-suited to get directly started on the **tutorials**.
 
    ---------------
 
-   :fa:`cloud,mr-1` **Virtual Machines**
+   :fa:`cloud,mr-1` **Run via virtual machine**
 
-   *Use a pre-made machine with all the required software.*
+   .. link-button:: https://quantum-mobile.readthedocs.io/
+      :text: Use a virtual machine with all the required software pre-installed.
+      :classes: stretched-link btn-link
 
    `Materials Cloud <https://www.materialscloud.org>`__ provides both downloadable and web based VMs,
    also incorporating pre-installed Materials Science codes.
 
-   +++
-
-   :link-badge:`https://materialscloud.org/quantum-mobile,Quantum Mobile,url,badge-primary text-white`
-   :link-badge:`https://aiidalab.materialscloud.org,AiiDA lab,url,badge-primary text-white`
-
-.. _intro:quick_start:
-
-Quick Start
-===========
-
-Here we first provide a simple approach for installation and setup on your local computer.
-
-Install Software
-----------------
-
-.. panels::
-    :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-2
-
-    :fa:`download,mr-1` **Install with conda**
-
-    .. parsed-literal::
-
-        conda create -n aiida -c conda-forge aiida-core=\ |release|\  aiida-core.services=\ |release|
-        conda activate aiida
-        reentry scan
-
-    `Conda <https://docs.conda.io>`__ provides a cross-platform package management system, from which we can install all the basic components of the AiiDA infrastructure in an isolated environment.
-
-    ----------------------------------------------
-
-    :fa:`download,mr-1` **Install with pip**
-
-    .. parsed-literal::
-
-        pip install aiida-core
-        reentry scan
-
-    ``aiida-core`` can be installed from `PyPi <https://pypi.org/project/aiida-core>`__.
-    It is strongly recommended that you install into a :ref:`virtual environment <intro:install:virtual_environments>`.
-    You will then need to install |PostgreSQL| and |RabbitMQ| depending on your operating system.
-
-    :link-badge:`intro:install:prerequisites,Install prerequisites,ref,badge-primary text-white`
-
-Initialise Data Storage
-------------------------
-
-Before working with AiiDA, you must first initialize a database storage area on disk.
-
-.. code-block:: console
-
-    $ initdb -D mylocal_db
-
-
-This *database cluster* may contain a collection of databases (one per profile) that is managed by a single running server process.
-We start this process with:
-
-.. code-block:: console
+.. _intro:get_started:next:
 
-    $ pg_ctl -D mylocal_db -l logfile start
+What's next?
+============
 
-.. admonition:: Further Reading
-    :class: seealso title-icon-read-more
-
-    - `Creating a Database Cluster <https://www.postgresql.org/docs/12/creating-cluster.html>`__.
-    - `Starting the Database Server <https://www.postgresql.org/docs/12/server-start.html>`__.
-
-Next, we set up an AiiDA configuration profile and related data storage, with the `quicksetup` command.
-
-.. code-block:: console
-
-    $ verdi quicksetup
-    Info: enter "?" for help
-    Info: enter "!" to ignore the default and set no value
-    Profile name: me
-    Email Address (for sharing data): me@user.com
-    First name: my
-    Last name: name
-    Institution: where-i-work
-
-At this point you now have a working AiiDA environment, from which you can add and retrieve data.
-
-.. admonition:: Tab Completion
-    :class: tip title-icon-lightbulb
-
-    Enable tab completion of ``verdi`` commands in the terminal with:
-
-    .. code-block:: console
-
-        $ eval "$(_VERDI_COMPLETE=source verdi)"
-
-    :link-badge:`how-to:installation:configure:tab-completion,Read More,ref,badge-primary text-white`
-
-Start Computation Services
---------------------------
-
-In order to run computations, some additional steps are required to start the services that manage these background processes.
-The |RabbitMQ| service is used, to manage communication between processes and retain process states, even after restarting your computer:
-
-.. code-block:: console
-
-    $ rabbitmq-server -detached
-
-We then start one or more "daemon" processes, which handle the execution and monitoring of all submitted computations.
-
-.. code-block:: console
-
-    $ verdi daemon start 2
-
-Finally, to check that all services are running as expected use:
-
-.. code-block:: console
-
-    $ verdi status
-    ✓ config dir:  /home/ubuntu/.aiida
-    ✓ profile:     On profile me
-    ✓ repository:  /home/ubuntu/.aiida/repository/me
-    ✓ postgres:    Connected as aiida_qs_ubuntu_c6a4f69d255fbe9cdb7385dcdcf3c050@localhost:5432
-    ✓ rabbitmq:    Connected as amqp://127.0.0.1?heartbeat=600
-    ✓ daemon:      Daemon is running as PID 16430 since 2020-04-29 12:17:31
-
-Awesome! You now have a fully operational installation from which to take the next steps!
-
-Stopping Services
------------------
-
-After finishing with your aiida session, particularly if switching between profiles, you may wish to power down the services:
-
-.. code-block:: console
-
-    $ verdi daemon stop
-    $ pg_ctl stop
-
-Any computations that are still running at this point, will be picked up next time the services are started.
-
-
-.. admonition:: Having problems?
-    :class: attention title-icon-troubleshoot
+After successfully completing one of the above outlined setup routes, if you are new to AiiDA, we recommed you go through the :ref:`Basic Tutorial <tutorial:basic>`,
+or see our :ref:`Next steps guide <tutorial:next-steps>`.
 
-    :ref:`See the troubleshooting section <intro:troubleshooting>`.
+If however, you encountered some issues, proceed to the :ref:`troubleshooting section <intro:troubleshooting>`.
 
 .. admonition:: In-depth instructions
     :class: seealso title-icon-read-more
 
-    For more ways to install AiiDA, :ref:`check the detailed installation section <intro:install>`.
-
     For more detailed instructions on configuring AiiDA, :ref:`see the configuration how-to <how-to:installation:configure>`.
 
-What Next?
-----------
-
-If you are new to AiiDA, go through the :ref:`Basic Tutorial <tutorial:basic>`,
-or see our :ref:`Next steps guide <tutorial:next-steps>`.
-
 .. |PostgreSQL| replace:: `PostgreSQL <https://www.postgresql.org>`__
 .. |RabbitMQ| replace:: `RabbitMQ <https://www.rabbitmq.com>`__
+.. |Homebrew| replace:: `Homebrew <https://brew.sh>`__