upgrade docs (#1038)

* upgrade docs

* add yaml example

* update docs

docs/CodeDevelopment.rst

@@ -3,42 +3,6 @@ Develop packages
 
 Spack offers several options for package development.
 Depending on your workflow, one or the other option is preferred.
-Also some packages like ICON or COSMO have their own 
-development workflow which is maintained by C2SM.
-
-Plain dev-build
----------------
-
-This is the easiest way to build local sources.
-Enter the root of your source repository and execute:
-
-.. code-block:: console
-
-    $ spack dev-build --until build <package> @<version>
-
-This will build the package as is. The downside of this approach is that
-you need to go through all phases of a package build.
-
-Dev-build in combination with build-env
----------------------------------------
-
-We assume that developers of a package are familiar with its build system.
-Therefore, we reccomend to use Spack to set up the environment for the package.
-Building and testing should be done with the package's build and test system.
-
-.. code-block:: console
-
-    # Load Spack!
-    $ spack dev-build --before build <package> @develop <variant> # stops dev-build before executing the phase 'build'
-    $ spack build-env <package> @develop <variant> -- bash # nests a bash shell with the build env vars loaded
-    # Work on the package!
-    # Use the build system of the package! (e.g. 'make')
-    # Use the testing infrastructure of the package!
-    $ exit # to exit the nested bash
-
-If you want multiple dev-builds at the same time, label them with separate ``@<your-label>``.
-The identifier ``@develop`` is common in the Spack documentation but you can use any string.
-
 
 Environments with Spack develop
 -------------------------------
@@ -95,3 +59,15 @@ To deactivate a Spack environment, type
 Most of the Spack commands are sensitive to environments, see 
 `Spack docs <https://spack.readthedocs.io/en/latest/environments.html#environment-sensitive-commands>`__.
 
+Plain dev-build
+---------------
+
+This is the easiest way to build local sources.
+Enter the root of your source repository and execute:
+
+.. code-block:: console
+
+    $ spack dev-build --until build <package> @<version>
+
+This will build the package as is. The downside of this approach is that
+you need to go through all phases of a package build.

docs/QuickStart.rst

@@ -11,19 +11,17 @@ To set up a Spack instance, clone the repository using a specific Spack tag (lat
 
   $ git clone --depth 1 --recurse-submodules --shallow-submodules -b $SPACK_TAG https://github.com/C2SM/spack-c2sm.git
 
-To load it into your command line, execute
+To load it into your command line, execute one of the following commands:
 
 .. code-block:: console
 
   $ . spack-c2sm/setup-env.sh
+  $ . spack-c2sm/setup-env.sh /user-environment
+  $ . spack-c2sm/setup-env.sh /mch-environment/v6
+  $ . spack-c2sm/setup-env.sh /mch-environment/v7
+  $ . spack-c2sm/setup-env.sh any_other_upstream
 
-This auto-detects your machine and configures your instance for it.
-You can force a machine with an argument. The name has to match a folder in sysconfigs.
-
-.. code-block:: console
-
-  $ . spack-c2sm/setup-env.sh balfrin
-
+This will make upstream installation from user-environment available in spack-c2sm.
 
 Local machines and Containers
 -----------------------------
@@ -89,16 +87,6 @@ For ICON, they are located in ``config/cscs/spack/<version>/<machine>_<target>_<
 They work with a special Spack tag, that is provided in the ICON repository at ``config/cscs/SPACK_TAG_*``.
 So make sure you clone Spack with the specified tag.
 
-..  tip::
-    **On Balfrin:** 
-    In case your Spack environment requires Python, a compatability issue
-    with `openssl` and `git` appears.
-
-    ``/usr/bin/ssh: symbol lookup error: /usr/bin/ssh: undefined symbol: EVP_KDF_CTX_free, version OPENSSL_1_1_1d``
-
-    To circumvent that simply do
-    ``spack load git`` prior to activation of the environment.
-
 To activate the Spack environment, type
 
 .. code-block:: console
@@ -127,15 +115,25 @@ Out-of-source builds are possible as follows:
 
 .. code-block:: console
 
-    $ mkdir cpu && cd cpu
-    $ cp -r ../config .
-    $ spack env activate -d config/cscs/spack/v0.20.1.5/daint_cpu_nvhpc
+    $ mkdir cpu
+    $ spack env activate config/cscs/spack/v0.20.1.5/daint_cpu_nvhpc
+    $ # tell spack to build icon in folder cpu
+    $ spack develop --build-directory cpu icon@develop
     $ spack install
 
-..  attention::
-    Out-of-source build for AutotoolsPackages is not supported by Spack.
-    The implementation for ICON relies on some hacks inside package.py and
-    only works if the build-folder is located inside the Git repo of ICON.
+By executing the commands above, spack will add some lines directly into ``spack.yaml``:
+
+.. code-block:: yaml
+
+  spack:                                                                                                                                                                                                                          
+    packages:                                                                                                                                                                                                                     
+      icon:                                                                                                                                                                                                                       
+        package_attributes:                                                                                                                                                                                                       
+          build_directory: /scratch/mch/juckerj/icon-nwp/cpu
+
+Any further ``spack install`` command will use the build directory specified in the ``spack.yaml`` file.
+In case you want to change the build directory, edit the ``spack.yaml`` file or remove the ``build_directory`` line
+and run ``spack concretize -f`` afterwards.
 
 COSMO
 -----