Docs: Reorganize the tutorial content (#6288)

The tutorials are moved to a separate page. A link is added to the `aiida-tutorials` repository as a source of additional tutorials. In the future, valuable tutorial information will be taken from there and directly integrated in the new tutorials page of the `aiida-core` docs. The "What is AiiDA" section is moved to the index page of the introduction.
aiidateam · Mar 8, 2024 · 5bd960e · 5bd960e
1 parent 5e4f60d
commit 5bd960e
Show file tree

Hide file tree

Showing 10 changed files with 74 additions and 31 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1378,7 +1378,7 @@ This command runs the `verdi` CLI using the currently loaded profile of the IPyt
 %verdi status
 ```
 
-See the [Basic Tutorial](docs/source/intro/tutorial.md) for example usage.
+See the [Basic Tutorial](docs/source/tutorials/basic.md) for example usage.
 
 ### New `SqliteTempBackend` ✨
 
@@ -1403,7 +1403,7 @@ profile = load_profile(
 )
 ```
 
-See the [Basic Tutorial](docs/source/intro/tutorial.md) for example usage.
+See the [Basic Tutorial](docs/source/tutorials/basic.md) for example usage.
 
 ### Key Pull Requests
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -49,15 +49,15 @@ Welcome to AiiDA's documentation!
 
          To the installation guides
 
-   .. grid-item-card:: :fa:`info-circle;mr-1` Tutorial
+   .. grid-item-card:: :fa:`info-circle;mr-1` Tutorials
       :text-align: center
       :shadow: md
 
-      First time users: Get your feet wet with AiiDA basics!
+      Concrete step-by-step examples.
 
       +++++++++++++++++++++++++++++++++++++++++++++
 
-      .. button-ref:: intro/tutorial
+      .. button-ref:: tutorials/index
          :ref-type: doc
          :click-parent:
          :expand:
@@ -154,6 +154,7 @@ Welcome to AiiDA's documentation!
    :hidden:
 
    intro/index
+   tutorials/index
    howto/index
    topics/index
    reference/index

diff --git a/docs/source/intro/about.rst b/docs/source/intro/about.rst
diff --git a/docs/source/intro/get_started.rst b/docs/source/intro/get_started.rst
@@ -17,6 +17,7 @@ An AiiDA installation consists of three core components (plus any external codes
    install_system
    install_conda
    run_docker
+   installation
 
 .. _intro:install:setup:
 .. _intro:get_started:setup:

diff --git a/docs/source/intro/index.rst b/docs/source/intro/index.rst
@@ -2,11 +2,34 @@
 Introduction
 ============
 
+.. _intro:about:
+
+
+*************
+What is AiiDA
+*************
+
+
+AiiDA is 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.
+
+AiiDA is built to support and streamline the four core pillars of the ADES model: Automation, Data, Environment, and Sharing (described `here <https://arxiv.org/abs/1504.01163>`__). Some of the key features of AiiDA include:
+
+*  **Workflows:** AiiDA allows to build and execute complex, auto-documenting workflows linked to multiple codes on local and remote computers.
+*  **High-throughput:** AiiDA's event-based workflow engine supports tens of thousands of processes per hour with full check-pointing.
+*  **Data provenance:** AiiDA automatically tracks and records inputs, outputs and metadata of all calculations and workflows in extensive provenance graphs that preserve the full lineage of all data.
+*  **Advanced queries:** AiiDA's query language enables fast graph queries on millions of nodes.
+*  **Plugin interface:** AiiDA can support via plugins any computational code and data analytics tool, data type, scheduler, connection mode, etc. (see `public plugin repository <https://aiidateam.github.io/aiida-registry/>`__).
+*  **HPC interface:** AiiDA can seamlessly deal with heterogeneous and remote computing resources; it works with many schedulers out of the box (`SLURM <https://slurm.schedmd.com>`__, `PBS Pro <https://www.pbspro.org/>`__, `torque <http://www.adaptivecomputing.com/products/torque/>`__, `SGE <http://gridscheduler.sourceforge.net/>`__ or `LSF <https://www.ibm.com/docs/en/spectrum-lsf>`__).
+*  **Open science:** AiiDA allows to export both full databases and selected subsets, to be shared with collaborators or made available and browsable online on the `Archive <https://archive.materialscloud.org/>`__ and `Explore <https://www.materialscloud.org/explore>`__ sections of `Materials Cloud <https://www.materialscloud.org>`__.
+*  **Open source:** AiiDA is released under the `MIT open-source license <https://github.com/aiidateam/aiida-core/blob/main/LICENSE.txt>`__.
+
+See also the `list of AiiDA-powered scientific publications <http://www.aiida.net/science/>`__ and `testimonials from AiiDA users <http://www.aiida.net/testimonials/>`__.
+
+
 .. toctree::
    :maxdepth: 1
 
-   about
    get_started
-   installation
-   tutorial
+   ../tutorials/index
+   Cheat sheet <https://aiida-tutorials.readthedocs.io/en/legacy/_downloads/5f69c3f9ce1f31f1f959b3da46fdc99d/cheatsheet.pdf>
    troubleshooting
diff --git a/docs/source/intro/tutorial.md → docs/source/tutorials/basic.md b/docs/source/intro/tutorial.md → docs/source/tutorials/basic.md
@@ -21,8 +21,7 @@ execution:
 (tutorial:basic)=
 # Basic tutorial
 
-Welcome to the AiiDA tutorial!
-The goal of this tutorial is to give you a basic idea of how AiiDA helps you in executing data-driven workflows.
+The goal of this tutorial is to give you an idea of how AiiDA helps you in executing data-driven workflows.
 At the end of this tutorial, you will know how to:
 
 - Store data in the database and subsequently retrieve it.
@@ -36,7 +35,7 @@ If this is not the case, consult the {ref}`getting started page<intro:get_starte
 :::
 
 :::{tip}
-This tutorial can be downloaded and run as a Jupyter Notebook: {nb-download}`tutorial.ipynb` {octicon}`download`
+This tutorial can be downloaded and run as a Jupyter Notebook: {nb-download}`basic.ipynb` {octicon}`download`
 :::
 
 ```{code-cell} ipython3

diff --git a/docs/source/intro/include/calcfun_graph.png → ...ource/tutorials/include/calcfun_graph.png b/docs/source/intro/include/calcfun_graph.png → ...ource/tutorials/include/calcfun_graph.png
diff --git a/docs/source/intro/include/calcjob_graph.png → ...ource/tutorials/include/calcjob_graph.png b/docs/source/intro/include/calcjob_graph.png → ...ource/tutorials/include/calcjob_graph.png
diff --git a/.../source/intro/include/workchain_graph.png → ...rce/tutorials/include/workchain_graph.png b/.../source/intro/include/workchain_graph.png → ...rce/tutorials/include/workchain_graph.png
diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst
@@ -0,0 +1,39 @@
+.. _tutorials:
+
+**********
+Tutorials
+**********
+
+For new users, it is recommended to start with the :ref:`basic tutorial <tutorial:basic>`.
+
+
+
+
+.. grid:: 1 1 2 2
+   :gutter: 3
+
+   .. grid-item-card:: :fa:`baby;mr-1` Basic tutorial
+
+      .. button-ref:: tutorial:basic
+         :ref-type: ref
+         :click-parent:
+         :class: btn-link
+
+         First time users: Get your feet wet with AiiDA!
+
+      This tutorial provides an introductory overview of AiiDA, demonstrating how calculations and workflows are run and how the data they generate is automatically stored in a provenance graph.
+
+
+   .. grid-item-card::  :fa:`fire;mr-1` Additional tutorials
+
+      `Additional tutorials <https://aiida-tutorials.readthedocs.io/en/latest/>`_
+
+      These tutorials were part of in-person hands-on workshops that have been organized since 2016. In addition to tutorials, they include Youtube videos of recorded presentations and demonstrations by the AiiDA team.
+
+
+
+.. toctree::
+   :maxdepth: 1
+
+   basic
+   Additional tutorials <https://aiida-tutorials.readthedocs.io/en/latest/>