Docs: Rework the installation section (#6455)

The `verdi setup` and `verdi quicksetup` commands have been deprecated and replaced by `verdi profile setup` and `verdi presto`. The installation docs were heavily outdated and the flow was scattered. The biggest change is that there now is a "quick install guide" that relies on `verdi presto` to provide an install route that is fool proof and will work on almost any system in a minimal amount of commands. Then there is the "complete installation guide" that provides all the details necessary to fully customize an installation.
aiidateam · Jun 28, 2024 · 0ee0a0c · 0ee0a0c
1 parent 66a2dce
commit 0ee0a0c
Show file tree

Hide file tree

Showing 27 changed files with 879 additions and 1,167 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -49,15 +49,9 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
-    'datatypes/**',
     'developer_guide/**',
-    'get_started/**',
-    'howto/installation_more/index.rst',
     'import_export/**',
     'internals/global_design.rst',
-    'internals/orm.rst',
-    'scheduler/index.rst',
-    'working_with_aiida/**',
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

diff --git a/docs/source/howto/daemon.rst b/docs/source/howto/daemon.rst
@@ -0,0 +1,13 @@
+
+.. _how-to:manage-daemon:
+
+How to manage the daemon
+------------------------
+
+The AiiDA daemon process runs in the background and takes care of processing your submitted calculations and workflows, checking their status, retrieving their results once they are finished and storing them in the AiiDA database.
+
+The AiiDA daemon is controlled using three simple commands:
+
+* ``verdi daemon start``: start the daemon
+* ``verdi daemon status``: check the status of the daemon
+* ``verdi daemon stop``: stop the daemon
diff --git a/docs/source/howto/index.rst b/docs/source/howto/index.rst
@@ -6,6 +6,7 @@ How-To Guides
    :maxdepth: 1
 
    interact
+   daemon
    plugins_install
    run_codes
    run_workflows

diff --git a/docs/source/howto/installation.rst b/docs/source/howto/installation.rst
@@ -14,7 +14,7 @@ Creating profiles
 -----------------
 Each AiiDA installation can have multiple profiles, each of which can have its own individual database and file repository to store the contents of the :ref:`provenance graph<topics:provenance:concepts>`.
 Profiles allow you to run multiple projects completely independently from one another with just a single AiiDA installation and at least one profile is required to run AiiDA.
-A new profile can be created using :ref:`verdi quicksetup<reference:command-line:verdi-quicksetup>` or :ref:`verdi setup<reference:command-line:verdi-setup>`, which works similar to the former but gives more control to the user.
+A new profile can be created using :ref:`verdi presto<reference:command-line:verdi-presto>` or :ref:`verdi profile setup<reference:command-line:verdi-profile>`, which works similar to the former but gives more control to the user.
 
 Listing profiles
 ----------------
@@ -296,7 +296,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, make sure to install AiiDA into a virtual environment, e.g., with conda or venv, as described :ref:`here <intro:get_started:setup>`.
+To isolate the code, make sure to install AiiDA into a virtual environment, e.g., with conda or venv.
 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.
@@ -619,12 +619,12 @@ Alternatively to the CLI command, one can also manually create a backup. This re
 .. _how-to:installation:backup:restore:
 
 Restoring data from a backup
-==================================
+============================
 
 Restoring a backed up AiiDA profile requires:
 
 * restoring the profile information in the AiiDA ``config.json`` file. Simply copy the`profiles` entry from
-  the backed up `config.json`to the one of the running AiiDA instance (see `verdi status` for exact location).
+  the backed up ``config.json`` to the one of the running AiiDA instance (see ``verdi status`` for exact location).
   Some information (e.g. the database parameters) might need to be updated.
 
 * restoring the data of of the backed up profile according to the ``config.json`` entry.
@@ -642,7 +642,7 @@ To test if the restoration worked, run ``verdi -p <profile-name> status`` to ver
 
         **PostgreSQL database**
 
-        To restore the PostgreSQL database from the ``db.psql`` file that was backed up, first you should create an empty database following the instructions described in :ref:`database <intro:install:database>` skipping the ``verdi setup`` phase.
+        To restore the PostgreSQL database from the ``db.psql`` file that was backed up, first you should create an empty database following the instructions described in :ref:`the installation guide <installation:guide-complete:create-profile:core-psql-dos>`.
         The backed up data can then be imported by calling:
 
         .. code-block:: console

diff --git a/docs/source/howto/interact.rst b/docs/source/howto/interact.rst
@@ -125,6 +125,18 @@ Interactive notebooks
 =====================
 
 Similar to :ref:`interactive shells <how-to:interact-shell>`, AiiDA is also directly compatbile with interactive Python notebooks, such as `Jupyter <https://jupyter.org/>`_.
+To install the required Python packages, install ``aiida-core`` with the ``notebook`` extra, e.g. run:
+
+.. code-block:: console
+
+    pip install aiida-core[notebook]
+
+You should now be able to start a Jupyter notebook server:
+
+.. code-block:: console
+
+    jupyter notebook
+
 To use AiiDA's Python API in a notebook, first a profile has to be loaded:
 
 .. code-block:: ipython
@@ -142,8 +154,14 @@ The same can be accomplished using the following magic statement:
     %load_ext aiida
     %aiida
 
-This magic line will replicate the same environment as :ref:`the interactive shell <how-to:interact-shell>` provided by ``verdi shell``.
-However, it does require some one-time installation, as detailed in the section on how to :ref:`intro:install:jupyter`.
+This magic line replicates the same environment as :ref:`the interactive shell <how-to:interact-shell>` provided by ``verdi shell``.
+
+It is also possible to run ``verdi`` commands inside the notebook, for example:
+
+.. code-block:: ipython
+
+   %verdi status
+
 
 
 .. _how-to:interact-restapi:

diff --git a/docs/source/howto/ssh.rst b/docs/source/howto/ssh.rst
@@ -269,6 +269,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:setup`).
+* install the ``ssh_kerberos`` extra during the installation of aiida-core (see :ref:`installation:guide-complete:python-package:optional-requirements`).
 
 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/index.rst b/docs/source/index.rst
@@ -1,9 +1,5 @@
 :sd_hide_title:
 
-#################################
-Welcome to AiiDA's documentation!
-#################################
-
 .. grid::
    :reverse:
    :gutter: 2 3 3 3
@@ -23,7 +19,8 @@ Welcome to AiiDA's documentation!
 
       .. rubric:: AiiDA
 
-      An open-source Python infrastructure to help researchers with automating, managing, persisting, sharing and reproducing the complex workflows associated with modern computational science and all associated data (see :ref:`features<intro:about>`).
+      An open-source Python infrastructure to help researchers with automating, managing, persisting, sharing and
+      reproducing the complex workflows associated with modern computational science and all associated data (see :ref:`features<intro>`).
 
       **aiida-core version:** |release|
 
@@ -32,15 +29,32 @@ Welcome to AiiDA's documentation!
 .. grid:: 1 2 2 2
    :gutter: 3
 
-   .. grid-item-card:: :fa:`rocket;mr-1` Getting Started
+   .. grid-item-card:: :fa:`circle-play;mr-1` Introduction
+      :text-align: center
+      :shadow: md
+
+      Overview of what AiiDA is and what it can do.
+
+      +++++++++++++++++++++++++++++++++++++++++++++
+
+      .. button-ref:: intro/index
+         :ref-type: doc
+         :click-parent:
+         :expand:
+         :color: primary
+         :outline:
+
+         To the introduction
+
+   .. grid-item-card:: :fa:`rocket;mr-1` Installation
       :text-align: center
       :shadow: md
 
-      AiiDA installation, configuration and troubleshooting.
+      Installation guides and troubleshooting.
 
       +++++++++++++++++++++++++++++++++++++++++++++
 
-      .. button-ref:: intro/get_started
+      .. button-ref:: installation/index
          :ref-type: doc
          :click-parent:
          :expand:
@@ -87,7 +101,7 @@ Welcome to AiiDA's documentation!
       :text-align: center
       :shadow: md
 
-      Background information on AiiDA's underlying concepts.
+      Background information on AiiDA concepts.
 
       +++++++++++++++++++++++++++++++++++++++++++++
 
@@ -104,7 +118,7 @@ Welcome to AiiDA's documentation!
       :text-align: center
       :shadow: md
 
-      Comprehensive documentation of AiiDA components: command-line interface, Python interface, and RESTful API.
+      Comprehensive documentation of CLI, Python API and REST API.
 
       +++++++++++++++++++++++++++++++++++++++++++++
 
@@ -121,7 +135,7 @@ Welcome to AiiDA's documentation!
       :text-align: center
       :shadow: md
 
-      Notes on AiiDA's design and architecture aimed at core developers.
+      Detailed information on AiiDA's design and architecture.
 
       +++++++++++++++++++++++++++++++++++++++++++++
 
@@ -154,15 +168,16 @@ Welcome to AiiDA's documentation!
    :hidden:
 
    intro/index
+   installation/index
    tutorials/index
    howto/index
    topics/index
    reference/index
    internals/index
 
-***********
+===========
 How to cite
-***********
+===========
 
 If you use AiiDA for your research, please cite the following work:
 
@@ -175,9 +190,9 @@ If the ADES concepts are referenced, please also cite:
 .. highlights:: Pizzi, Giovanni, Andrea Cepellotti, Riccardo Sabatini, Nicola Marzari, and Boris Kozinsky. *AiiDA: automated interactive infrastructure and database for computational science*, Computational Materials Science **111**, 218-230 (2016); DOI: `10.1016/j.commatsci.2015.09.013 <https://doi.org/10.1016/j.commatsci.2015.09.013>`_
 
 
-****************
+================
 Acknowledgements
-****************
+================
 
 AiiDA is supported by the `MARVEL National Centre of Competence in Research`_, the `MaX European Centre of Excellence`_ and by a number of other supporting projects, partners and institutions, whose complete list is available on the `AiiDA website acknowledgements page`_.