Merge pull request #2709 from vkarak/doc/whats-new-4.0

[doc] Add a "What's New" page for ReFrame 4.0

Author: vkarak

docs/config_reference.rst

@@ -7,8 +7,6 @@ This will allow you to run simple local tests using the default compiler of the
 Of course, ReFrame is much more powerful than that.
 This section will guide you through configuring ReFrame for your site.
 
-If you started using ReFrame from version 3.0, you can keep on reading this section, otherwise you are advised to have a look first at the :doc:`migration_2_to_3` page.
-
 ReFrame's configuration can be either in JSON or in Python format and can be split into multiple files.
 The Python format is useful in cases that you want to generate configuration parameters on-the-fly, since ReFrame will import that Python file and the load the resulting configuration.
 In the following we will use a single Python-based configuration file also for historical reasons, since it was the only way to configure ReFrame in versions prior to 3.0.
@@ -222,6 +220,8 @@ The ``modes`` section defines different execution modes for the framework.
 Execution modes are discussed in the :doc:`pipeline` page.
 
 
+.. _building-the-final-config:
+
 Building the Final Configuration
 --------------------------------
 

docs/configure.rst

@@ -45,9 +45,9 @@ Webinars
    :maxdepth: 2
 
    started
+   whats_new_40
    tutorials
    configure
    topics
-   migration_2_to_3
    manuals
    hpctestlib

docs/index.rst

@@ -188,8 +188,8 @@ The following table show in which context each pipeline stage executes:
    ============== =================
 
 It should be noted that even if the partition execution context is local, it is treated differently from the ReFrame execution context.
-For example, a test executing in the ReFrame context will not respect the :js:attr:`max_jobs` partition configuration option, even if the partition is local.
-To control the concurrency of the ReFrame execution context, users should set the :js:attr:`.systems[].max_local_jobs` option instead.
+For example, a test executing in the ReFrame context will not respect the :attr:`~config.systems.partitions.max_jobs` partition configuration option, even if the partition is local.
+To control the concurrency of the ReFrame execution context, users should set the :attr:`~config.systems.max_local_jobs` option instead.
 
 
 .. versionchanged:: 3.10.0

docs/manpage.rst

@@ -348,4 +348,4 @@ Mapping of Test Attributes to Job Scheduler Backends
 If any of the attributes is set to :class:`None` it will not be emitted at all in the job script.
 In cases that the attribute is required, it will be set to ``1``.
 
-:sup:`1` The :obj:`--nodes` option may also be emitted if the :js:attr:`use_nodes_option <config_reference.html#schedulers-.use_nodes_option>` scheduler configuration parameter is set.
+:sup:`1` The :obj:`--nodes` option may also be emitted if the :attr:`~config.systems.partitions.sched_options.use_nodes_option` scheduler configuration parameter is set.

docs/migration_2_to_3.rst

@@ -118,6 +118,10 @@ Auto-completion is supported for Bash, Tcsh and Fish shells.
 Where to Go from Here
 ---------------------
 
-The easiest way to start with ReFrame is to go through :doc:`tutorial_basics`, which will guide you step-by-step in both writing your first tests and in configuring ReFrame.
-The :doc:`configure` page provides more details on the basic configuration aspects of ReFrame.
-:doc:`topics` explain different aspects of the framework whereas :doc:`manuals` provide complete reference guides for the command line interface, the configuration parameters and the programming APIs for writing tests.
+If you are new to ReFrame, the place to start is the first tutorial :doc:`tutorial_basics`, which will guide you step-by-step in both writing your first tests and in configuring ReFrame.
+The rest of the tutorials explore additional capabilities of the framework and cover several topics that you will likely come across when writing your own tests.
+
+The :doc:`configure` page provides more details on how a configuration file is structured and the :doc:`topics` explain some more advanced concepts as well as some implementation details.
+The :doc:`manuals` provide complete reference guides for the command line interface, the configuration parameters and the programming APIs for writing tests.
+
+Finally, if you are not new to ReFrame and you have been using the 3.x versions, you should read the :doc:`whats_new_40` page, which explains what are the key new features of ReFrame 4.0 as well as all the breaking changes.

docs/pipeline.rst

@@ -390,7 +390,7 @@ Generally, ReFrame generates the job shell scripts using the following pattern:
 
 The ``job_scheduler_preamble`` contains the backend job scheduler directives that control the job allocation.
 The ``prepare_cmds`` are commands that can be emitted before the test environment commands.
-These can be specified with the :js:attr:`prepare_cmds <.systems[].partitions[].prepare_cmds>` partition configuration option.
+These can be specified with the :attr:`~config.systems.partitions.prepare_cmds` partition configuration option.
 The ``env_load_cmds`` are the necessary commands for setting up the environment of the test.
 These include any modules or environment variables set at the `system partition level <config_reference.html#system-partition-configuration>`__ or any `modules <regression_test_api.html#reframe.core.pipeline.RegressionTest.modules>`__ or `environment variables <regression_test_api.html#reframe.core.pipeline.RegressionTest.variables>`__ set at the test level.
 Then the commands specified in :attr:`~reframe.core.pipeline.RegressionTest.prerun_cmds` follow, while those specified in the :attr:`~reframe.core.pipeline.RegressionTest.postrun_cmds` come after the launch of the parallel job.
@@ -613,6 +613,8 @@ Let's see how the generated job script looks like:
 The first three ``srun`` commands are emitted through the :attr:`prerun_cmds` whereas the last one comes from the test's :attr:`executable` attribute.
 
 
+.. _custom_launchers:
+
 Adding a custom launcher to a partition
 =======================================
 
@@ -723,8 +725,8 @@ First, we need to enable the container platform support in ReFrame's configurati
    :end-before: # rfmdocend: containers
    :emphasize-lines: 9-18
 
-For each partition, users can define a list of container platforms supported using the :js:attr:`container_platforms` `configuration parameter <config_reference.html#.systems[].partitions[].container_platforms>`__.
-In this case, we define the `Sarus <https://github.com/eth-cscs/sarus>`__ platform for which we set the :js:attr:`modules` parameter in order to instruct ReFrame to load the ``sarus`` module, whenever it needs to run with this container platform.
+For each partition, users can define a list of all supported container platforms using the :attr:`~config.systems.partitions.container_platforms` configuration parameter.
+In this case, we define the `Sarus <https://github.com/eth-cscs/sarus>`__ platform for which we set the :attr:`~config.systems.partitions.container_platforms.modules` parameter in order to instruct ReFrame to load the ``sarus`` module, whenever it needs to run with this container platform.
 Similarly, we add an entry for the `Singularity <https://sylabs.io>`__ platform.
 Optionally, users are allowed to set the ``default`` attribute to :obj:`True` in order to mark a specific container platform as the default of that partition (see below on how this information is being used).
 If no default container platform is specified explicitly, then always the first in the list will be considered as successful.