add reframe how to docs (#147)

Refactor the documentation to more clearly separate between docs for users and CSCS staff

Add a tutorial for CSCS staff writing reframe tests.

docs/developers-overview.md

@@ -0,0 +1,7 @@
+# Documentation for uenv developers
+
+The documentation here is a collection of best practices and practical how-to for folk writing uenv recipes, specifically for the Alps targets at CSCS.
+
+* A practical [recipe writing guide](pkg-application-tutorial.md);
+* A step-by-step guide for [supporting ReFrame tests](pkg-reframe.md) in the CSCS regression testing framework;
+* A guide on how to [write uenv documentation](pkg-writing-docs.md) for this site.

docs/index.md

@@ -1,71 +1,11 @@
-# CSCS User Environments
+# CSCS uenv
 
-Documentation for the user-environments provided on CSCS Alps infrastructure.
+This site provides the following documentation for users of uenv on Alps:
 
-## Writing Documentation
+* [uenv provided on Alps](uenv-overview.md).
+* [tutorials on using uenv](tutorial-overview.md).
 
-The documentation for uenv is written with [Material for mkdocs](https://squidfunk.github.io/mkdocs-material/).
+## uenv developers
 
-See the documentation for Material for details on all of the features that it provides.
+CSCS staff developing uenv can find the following best practices and pracitical guides for [developing uenv](developers-overview.md).
 
-### Getting Started
-
-To view the documentation as you write, you can install Material for mkdocs using pip.
-
-First, create Python virtual environment and install `mkdocs-material`
-```bash
-# create and activate a venv
-python3 -m venv pyenv
-source pyenv/bin/activate
-
-# install required packages
-pip install --upgrade pip
-pip install mkdocs-material
-```
-
-!!! note
-
-    If you just created the python virtual environment, you might have to restart it for the `mkdocs` executable to be added to `PATH`.
-
-    ```bash
-    # you have to deactivate and start again for mkdocs to be available
-    deactivate
-    source pyenv/bin/activate
-    ```
-
-The documentation is built using the `mkdocs` executable.
-To view your documentation in your browser, run the mkdocs server:
-```bash
-mkdocs serve
-```
-
-Leave it running, and every time you save the markdown file the docs will be regenerated.
-
-The docs can be viewed by using the link printed by `mkdocs serve`:
-
-```
-mkdocs serve                                                                                                  (pyenv) main [e2006ad] Δ ?
-INFO    -  Building documentation...
-INFO    -  Cleaning site directory
-INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
-             - writing-docs.md
-INFO    -  Documentation built in 0.15 seconds
-INFO    -  [12:17:14] Watching paths for changes: 'docs', 'mkdocs.yml'
-INFO    -  [12:17:14] Serving on http://127.0.0.1:8000/
-```
-
-And viewing it ( [http://127.0.0.1:8000/](http://127.0.0.1:8000/) typically) in your local browser.
-
-### Documentation Layout
-
-To add documentation for a uenv, create a file `docs/uenv-<uenv name>.md`, and look at existing documentation to get started.
-
-For your docs to be generated, it has to be added to the index in the `mkdocs.yml` file in the root of the repository. For example, to add docs for a new environment called `wombat`:
-
-```yaml
-nav:
-  - Home: index.md
-  - 'uenv':
-    - 'Overview': uenv-overview.md
-    - 'wombat': uenv-wombat.md
-```