Merge pull request #3095 from vkarak/doc/new-tutorial

[doc] Revamp the documentation

Author: vkarak

.github/workflows/main.yml

@@ -86,7 +86,7 @@ jobs:
       run: |
         docker run reframe-${{ matrix.modules-version }}:latest
 
-  tutorialtest:
+  eb-spack-howto:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
@@ -99,7 +99,7 @@ jobs:
     - name: Build Image for Tutorial Tests
       run: |
         echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $ --password-stdin
-        docker build -f ci-scripts/dockerfiles/tutorials.dockerfile -t reframe-tutorials:latest .
+        docker build -f ci-scripts/dockerfiles/eb-spack-howto.dockerfile -t reframe-tutorials:latest .
         docker logout
     - name: Run Tutorial Tests
       run: |

.github/workflows/test-flux.yaml

@@ -38,6 +38,6 @@ jobs:
         run: |
           export PATH=$PWD/bin:$PATH
           which reframe
-          flux start reframe -c tutorials/flux -C tutorials/flux/settings.py -l
-          flux start reframe -c tutorials/flux -C tutorials/flux/settings.py --run
-          flux start python3 ./test_reframe.py --rfm-user-config=tutorials/flux/settings.py -vvvv
+          flux start reframe -c examples/howto/flux -C examples/howto/flux/settings.py -l
+          flux start reframe -c examples/howto/flux -C examples/howto/flux/settings.py -r
+          flux start python3 ./test_reframe.py --rfm-user-config=examples/howto/flux/settings.py -vvvv

ci-scripts/dockerfiles/tutorials.dockerfile renamed to ci-scripts/dockerfiles/eb-spack-howto.dockerfile

@@ -37,4 +37,4 @@ RUN echo '. /usr/local/lmod/lmod/init/profile && . /home/rfmuser/spack/share/spa
 
 ENV BASH_ENV /home/rfmuser/setup.sh
 
-CMD ["/bin/bash", "-c", "./bin/reframe -r -C tutorials/config/lmodsys.py -R -c tutorials/build_systems"]
+CMD ["/bin/bash", "-c", "./bin/reframe --system=tutorialsys -r -C examples/tutorial/config/baseline_modules.py -R -c examples/tutorial/easybuild/eb_test.py -c examples/tutorial/spack/spack_test.py"]

docs/_static/img/reframe-system-arch.svg

@@ -2,7 +2,7 @@
 Configuration Reference
 ***********************
 
-ReFrame's behavior can be configured through its configuration file (see :doc:`configure`), environment variables and command-line options.
+ReFrame's behavior can be configured through its configuration file, environment variables and command-line options.
 An option can be specified via multiple paths (e.g., a configuration file parameter and an environment variable), in which case command-line options precede environment variables, which in turn precede configuration file options.
 This section provides a complete reference guide of the configuration options of ReFrame that can be set in its configuration file or specified using environment variables.
 
@@ -577,7 +577,24 @@ System Partition Configuration
    :default: ``{}``
 
    Processor information for this partition stored in a `processor info object <#processor-info>`__.
-   If not set, ReFrame will try to auto-detect this information (see :ref:`proc-autodetection` for more information).
+   If not set, ReFrame will try to determine this information as follows:
+
+   #. If the processor configuration metadata file in ``~/.reframe/topology/{system}-{part}/processor.json`` exists, the topology information is loaded from there.
+      These files are generated automatically by ReFrame from previous runs.
+
+   #. If the corresponding metadata files are not found, the processor information will be auto-detected.
+      If the system partition is local (i.e., ``local`` scheduler + ``local`` launcher), the processor information is auto-detected unconditionally and stored in the corresponding metadata file for this partition.
+      If the partition is remote, ReFrame will not try to auto-detect it unless the :envvar:`RFM_REMOTE_DETECT` or the :attr:`general.remote_detect` configuration option is set.
+      In that case, the steps to auto-detect the remote processor information are the following:
+
+        a. ReFrame creates a fresh clone of itself in a temporary directory created under ``.`` by default.
+           This temporary directory prefix can be changed by setting the :envvar:`RFM_REMOTE_WORKDIR` environment variable.
+        b. ReFrame changes to that directory and launches a job that will first bootstrap the fresh clone and then run that clone with ``{launcher} ./bin/reframe --detect-host-topology=topo.json``.
+           The :option:`--detect-host-topology` option causes ReFrame to detect the topology of the current host,
+           which in this case would be one of the remote compute nodes.
+
+      In case of errors during auto-detection, ReFrame will simply issue a warning and continue.
+
 
    .. versionadded:: 3.5.0
 
@@ -1670,7 +1687,6 @@ General Configuration
 
    Try to auto-detect processor information of remote partitions as well.
    This may slow down the initialization of the framework, since it involves submitting auto-detection jobs to the remote partitions.
-   For more information on how ReFrame auto-detects processor information, you may refer to :ref:`proc-autodetection`.
 
    .. versionadded:: 3.7.0