Docs: add "How to manage your installation - Managing profiles" (#4066)

This is a new section that is intended to describe the function of
profiles and the various commands that can be used to work with them.
Note that the explanation on the purpose and details of profiles is kept
to a minimum as this is a How-to guide and is merely intended to help
users with goal oriented problems.

The section quickly explains the various profile commands:

    * verdi profile list
    * verdi profile setdefault
    * verdi profile show
    * verdi profile delete

Information on how further configuration through profiles is reserved
for the next how-to section "Configuring your installation".

docs/source/howto/installation.rst

@@ -10,7 +10,63 @@ How to manage your installation
 Managing profiles
 =================
 
-`#4000`_
+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.
+
+Listing profiles
+----------------
+The :ref:`verdi profile<reference:command-line:verdi-profile>` command line interface provides various commands to manage the profiles of an AiiDA installation.
+To list the currently configured profiles, use ``verdi profile list``:
+
+.. code:: bash
+
+    Info: configuration folder: /home/user/.virtualenvs/aiida/.aiida
+    * project-one
+      project-two
+
+In this particular example, there are two configured profiles, ``project-one`` and ``project-two``.
+The first one is highlighted and marked with a ``*`` symbol, meaning it is the default profile.
+A profile being the default means simply that any ``verdi`` command will always be executed for that profile.
+You can :ref:`change the profile on a per-call basis<topics:cli:profile>` with the ``--p/--profile`` option.
+To change the default profile use ``verdi profile setdefault PROFILE``.
+
+Showing profiles
+----------------
+Each profile defines various parameters, such as the location of the file repository on the file system and the connection parameters for the database.
+To display these parameters, use ``verdi profile show``:
+
+.. code:: bash
+
+    Info: Profile: project-one
+    ----------------------  ------------------------------------------------
+    aiidadb_backend         django
+    aiidadb_engine          postgresql_psycopg2
+    aiidadb_host            localhost
+    aiidadb_name            aiida_project_one
+    aiidadb_pass            correcthorsebatterystaple
+    aiidadb_port            5432
+    aiidadb_repository_uri  file:///home/user/.virtualenvs/aiida/repository/
+    aiidadb_user            aiida
+    default_user_email      user@email.com
+    options                 {'daemon_default_workers': 3}
+    profile_uuid            4c272a87d7f543b08da9fe738d88bb13
+    ----------------------  ------------------------------------------------
+
+By default, the parameters of the default profile are shown, but one can pass the profile name of another, e.g., ``verdi profile show project-two`` to change that.
+
+Deleting profiles
+-----------------
+A profile can be deleted using the ``verdi profile delete`` command.
+By default, deleting a profile will also delete its file repository and the database.
+This behavior can be changed using the ``--skip-repository`` and ``--skip-db`` options.
+
+.. note::
+
+    In order to delete the database, the system user needs to have the required rights, which is not always guaranteed depending on the system.
+    In such cases, the database deletion may fail and the user will have to perform the deletion manually through PostgreSQL.
 
 
 .. _how-to:installation:configure:
@@ -54,7 +110,6 @@ Managing multiple users
 
 
 
-.. _#4000: https://github.com/aiidateam/aiida-core/issues/4000
 .. _#4001: https://github.com/aiidateam/aiida-core/issues/4001
 .. _#4002: https://github.com/aiidateam/aiida-core/issues/4002
 .. _#4003: https://github.com/aiidateam/aiida-core/issues/4003

docs/source/index.rst

@@ -136,6 +136,7 @@ Welcome to AiiDA's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Internal architecture
+   :hidden:
 
    internals/global_design
    internals/orm