DOC: new docker stack update and add placeholder section for docker d…

…esktop (#572)

Adding section for docker desktop and update the documentation organization of docker running part.

docs/requirements.in

@@ -1,3 +1,3 @@
 sphinx~=4.5.0
 sphinx-design~=0.4.1
-pydata-sphinx-theme==0.8.0
+pydata-sphinx-theme==0.13.3

docs/requirements.txt

@@ -1,13 +1,17 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.9
 # by the following command:
 #
 #    pip-compile docs/requirements.in
 #
+accessible-pygments==0.0.4
+    # via pydata-sphinx-theme
 alabaster==0.7.13
     # via sphinx
 babel==2.12.1
-    # via sphinx
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
 beautifulsoup4==4.12.2
     # via pydata-sphinx-theme
 certifi==2023.5.7
@@ -22,16 +26,23 @@ idna==3.4
     # via requests
 imagesize==1.4.1
     # via sphinx
+importlib-metadata==6.8.0
+    # via sphinx
 jinja2==3.1.2
     # via sphinx
 markupsafe==2.1.3
     # via jinja2
 packaging==23.1
-    # via sphinx
-pydata-sphinx-theme==0.8.0
+    # via
+    #   pydata-sphinx-theme
+    #   sphinx
+pydata-sphinx-theme==0.13.3
     # via -r docs/requirements.in
 pygments==2.15.1
-    # via sphinx
+    # via
+    #   accessible-pygments
+    #   pydata-sphinx-theme
+    #   sphinx
 requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
@@ -57,5 +68,9 @@ sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
+typing-extensions==4.8.0
+    # via pydata-sphinx-theme
 urllib3==2.0.3
     # via requests
+zipp==3.17.0
+    # via importlib-metadata

docs/source/conf.py

@@ -18,6 +18,8 @@
 
 # -- Project information -----------------------------------------------------
 
+version = "v23.10.0rc0"
+release = f"{version}-dev"
 project = "Quantum ESPRESSO App"
 copyright_first_year = "2023"
 copyright_owners = "The AiiDAlab Team"

docs/source/index.rst

@@ -11,7 +11,7 @@ Welcome Page
       :child-align: justify
       :class: sd-fs-5
 
-      .. rubric:: The Quantum ESPRESSO App - Version 23.10.0a0
+      .. rubric:: The Quantum ESPRESSO App - Version |release|
 
       The Quantum ESPRESSO (QE) app is an `AiiDAlab`_ Jupyter-based graphical user interface allowing users to conduct and streamline many of `Quantum ESPRESSO`_'s calculations by leveraging `AiiDA`_'s powerful workflows implemented in the AiiDA Quantum ESPRESSO plugin.
 

docs/source/installation/access_aiidalab/container.rst

@@ -0,0 +1,110 @@
+========================
+Local Container Instance
+========================
+
+.. note::
+
+   If you already have access to AiiDAlab but the Quantum ESPRESSO app is not installed, you need proceed to :doc:`install the app </installation/install>`.
+
+AiiDAlab is available as a Docker container - a self-contained, pre-configured environment including all the necessary software to access the AiiDAlab platform.
+We also provide container that includes the Quantum ESPRESSO app installed and ready to use.
+To run the container, you first need to install Docker on your local machine.
+If you have yet to do so, you may click `here <https://docs.docker.com/get-docker>`_ to follow the official Docker installation guide.
+
+We recommended to install the `Docker Desktop <https://docs.docker.com/desktop/>`_ which is available for all major operating systems.
+
+.. important::
+
+   On Linux, if the docker is installed by `docker engine <https://docs.docker.com/engine/install/ubuntu/>`_, you need `root` privileges to perform the `post-installation steps for Docker Engine <https://docs.docker.com/engine/install/linux-postinstall/>`_. There is **NO NEED** to perform this step if the docker is installed by `docker desktop <https://docs.docker.com/docker-for-windows/install/>`_.
+
+Once Docker is installed, you can launch the container in one of several ways depending on your operating system.
+This is discussed in the following sections.
+
+Docker Desktop
+**************
+
+If you use Windows, this may be the easiest way to launch the container.
+For MacOS and Linux, you can also use Docker Desktop, but you may prefer to use the command line interface (CLI), see the next sections.
+
+Comming soon with video tutorial.
+
+AiiDAlab launch
+***************
+
+.. important::
+
+   The following steps require a local installation of Docker.
+   You can check the docker is properly installed by running ``docker run hello-world`` in the terminal.
+
+`AiiDAlab launch`_ is a thin Docker wrapper which takes care of all the prerequisites to run the AiiDAlab Docker image.
+It helps to manage multiple AiiDAlab profiles, each with its own home directory for persistent storage, and allows to easily switch between them.
+To use AiiDAlab launch, you will have to
+
+#. Install AiiDAlab launch with `pipx <https://pypa.github.io/pipx/installation/>`_ (**recommended**):
+
+   .. code-block:: console
+
+      pipx install aiidalab-launch
+
+   or directly with pip
+
+   .. code-block:: console
+
+      pip install aiidalab-launch
+
+#. Set up a new `QE` profile with
+
+   .. code-block:: console
+
+      aiidalab-launch profile add --image aiidalab/qe:latest QE
+
+   At the prompt, enter `n` to skip editing the profile settings.
+
+#. Start AiiDAlab with
+
+   .. code-block:: console
+
+       aiidalab-launch start -p QE
+
+#. Follow the URL on the screen to open AiiDAlab in the browser
+
+.. tip::
+
+   For more detailed help, run
+
+   .. code-block:: console
+
+      aiidalab-launch --help
+
+Profile Management
+^^^^^^^^^^^^^^^^^^
+
+As shown above, you can manage multiple profiles in AiiDAlab launch, e.g., with different home directories or ports. For more information, run
+
+.. code-block:: console
+
+   aiidalab-launch profiles --help
+
+You can inspect the status of all configured AiiDAlab profiles with
+
+.. code-block:: console
+
+   aiidalab-launch status
+
+.. _`AiiDAlab launch`: https://github.com/aiidalab/aiidalab-launch
+
+Using docker CLI directly
+*************************
+
+It is not necessary to use AiiDAlab launch to run the AiiDAlab container.
+You can also use the docker CLI directly by running
+
+.. code-block:: console
+
+   docker run -p 8888:8888 aiidalab/qe:latest
+
+Follow the URL on the screen to open AiiDAlab in the browser.
+
+.. important::
+
+   If you use the docker CLI directly, the data in the home directory of the container will be lost when the container is deleted. You can use the ``-v`` option to mount a local directory to the container to store the data persistently. For more information, run ``docker run --help``.

docs/source/installation/aiidalab/index.rst → docs/source/installation/access_aiidalab/index.rst

@@ -9,71 +9,55 @@ Access AiiDAlab
 .. grid:: 1 1 1 2
    :gutter: 3
 
-   .. grid-item-card:: Local Docker Instance
+   .. grid-item-card:: Materials Cloud AiiDAlab Server
       :text-align: center
       :shadow: md
 
-      Install Docker locally and run an instance of an AiiDAlab image *pre-configured** for the Quantum ESPRESSO app. No prior knowledge of Docker necessary!
+      For researchers affiliated with Materials Cloud partners, log into the open AiiDAlab server hosted on the Materials Cloud.
 
       ++++
 
-      .. button-ref:: docker
-         :ref-type: doc
+      .. button-link:: https://aiidalab.materialscloud.org/hub/login
          :click-parent:
          :expand:
          :color: primary
          :outline:
 
-         To the guide
+         Launch the server
 
-   .. grid-item-card:: Virtual Machine Image
+   .. grid-item-card:: Local Docker Instance
       :text-align: center
       :shadow: md
 
-      Download a virtual machine image for AiiDAlab based on Quantum Mobile, *pre-configured** with everything you need to run the Quantum ESPRESSO app.
+      Install Docker locally and run an instance of an AiiDAlab image *pre-configured** for the Quantum ESPRESSO app. No prior knowledge of Docker necessary!
 
       ++++
 
-      .. button-ref:: vm
+      .. button-ref:: container
          :ref-type: doc
          :click-parent:
          :expand:
          :color: primary
          :outline:
 
-         To the download page
-
-   .. grid-item-card:: Materials Cloud AiiDAlab Server
-      :text-align: center
-      :shadow: md
-
-      For researchers affiliated with Materials Cloud partners, log into the open AiiDAlab server hosted on the Materials Cloud.
-
-      ++++
-
-      .. button-link:: https://aiidalab.materialscloud.org/hub/login
-         :click-parent:
-         :expand:
-         :color: primary
-         :outline:
-
-         Launch the server
+         To the guide
 
-   .. grid-item-card:: Materials MarketPlace AiiDAlab Server
+   .. grid-item-card:: Virtual Machine Image
       :text-align: center
       :shadow: md
 
-      For members of the Materials Modeling MarketPlace, log into the open AiiDAlab server hosted on the Materials MarketPlace.
+      Download a virtual machine image for AiiDAlab based on Quantum Mobile, *pre-configured** with everything you need to run the Quantum ESPRESSO app.
 
       ++++
 
-      .. button-link:: https://aiidalab.materials-marketplace.eu/hub/login
+      .. button-ref:: vm
+         :ref-type: doc
          :click-parent:
          :expand:
          :color: primary
          :outline:
 
-         Launch the server
+         To the download page
 
 .. div::
 
@@ -83,6 +67,5 @@ Access AiiDAlab
    :maxdepth: 1
    :hidden:
 
-   docker
-   launch
+   container
    vm

docs/source/installation/index.rst

@@ -7,6 +7,6 @@ The following links will guide you through the necessary steps to access the Aii
 .. toctree::
    :maxdepth: 1
 
-   aiidalab/index
+   access_aiidalab/index
    install
    launch