Migrate docs into main repository tree (#358)

Closes #357.

docs/README.md

@@ -0,0 +1,18 @@
+# Swell Workflow Ecosystem, Layout and Launcher
+
+The swell system is developed by NASA's [Global Modeling and Assimilation Office](https://gmao.gsfc.nasa.gov/). It is used to generate experiments using the [JEDI](https://www.jcsda.org/jcsda-project-jedi) data assimilation system and NASA's [Goddard Earth Observing System (GEOS)](https://gmao.gsfc.nasa.gov/GEOS_systems/) numerical weather forecast model. Specifically, swell is designed with coupled data assimilation applications in mind and can be used to deploy cycled experiments for a coupled system.
+
+Swell is written entirely using Python with configuration files written using YAML.
+
+Swell has several responsibilities:
+
+- To provide the tasks that make up the workflow. For example moving around observation files.
+- To generate the suite files that describe the workflow order and that can be read by the workflow manager.
+- To provide example configuration files that can be used to generate experiments.
+- To provide the scripts that create, modify and launch experiments.
+- To provide configuration for the individual components of the Earth system and the observing system.
+- To provide platform/machine specific files that can be used to run experiments.
+
+### Workflow manager
+
+Swell uses the [`cylc`](https://cylc.github.io/) workflow manager to launch and then monitor experimentation. While the suite files are specific to `cylc`, the tasking and general configuration files are not and it would be fairly straightforward to write suite files that direct swell tasks through an alternative workflow manager such as `ecflow`.

docs/_coverpage.md

@@ -0,0 +1,8 @@
+# swell
+
+> Workflow system for coupled data assimilation applications
+
+[GitHub](https://github.com/GEOS-ESM/swell)
+[Documentation](#swell-workflow-ecosystem-layout-and-launcher)
+
+![](_media/swell.jpeg)

docs/_sidebar.md

@@ -0,0 +1,38 @@
+- Getting started
+
+  - [Installing swell](installing_swell.md)
+  - [Configuring `cylc`](configuring_cylc.md)
+  - [Creating an experiment](creating_an_experiment.md)
+  - [Launching an experiment](launching_an_experiment.md)
+  - [Monitoring an experiment](monitoring_an_experiment.md)
+  - [Manually running tasks](manually_running_tasks.md)
+
+
+- Platform specific instructions
+
+  - [Platforms](platforms/platforms.md)
+  - **Discover**
+    - [Installing swell](platforms/discover/installing_swell_discover.md)
+    - [Configuring `cylc`](platforms/discover/configuring_cylc_discover.md)
+
+- Practical Examples
+
+  - [Description](examples/description.md)
+  - **SOCA**
+    -  [3DVAR](examples/soca/3dvar.md)
+
+- Configuration files in swell
+
+  - [Observation configuration](observation_configuration.md)
+  - [Model configuration](model_configuration.md)
+
+- Tasks
+
+  - [Task infrastructure](task_infrastructure.md)
+  - [Tasks](tasks.md)
+
+- Governance
+
+  - [Requirements](requirements.md)
+
+- [Useful links](useful_links.md)

docs/configuring_cylc.md

@@ -0,0 +1,13 @@
+# Configuring `cylc`
+
+Before you can run a swell generated workflow it's necessary to configure `cylc`. This is only done before the first run, or when the `cylc` version needs to be updated or when the behavior of `cylc` needs to be modified.
+
+For the first step of this configuration it is necessary to ensure `cylc` is immediately visible in your path when starting a new session. This is achieved by creating a file `$HOME/bin/cylc` (which is typically in the path). This file can then add additional things to the path to start `cylc`.
+
+Additionally `cylc` uses a file called `$HOME/.cylc/flow/global.cylc` to control common aspects of the workflow system. The `cylc` documentation describes some of the things controlled by `global.cylc`.
+
+
+---
+**WARNING:**
+The contents of the above two files will be platform specific.
+---

docs/creating_an_experiment.md

@@ -0,0 +1,18 @@
+# Creating an experiment using Swell
+
+Once you have installed `swell` and configured `cylc` you should be able to create and run an experiment.
+
+A useful command when using swell is `swell --help`. This will take you through all the options within swell. The help traverses through the applications so you can similarly issue `swell create --help`
+
+The first step is to create an experiment which is done with
+
+```bash
+swell create <suite> <options>
+```
+
+This will create a directory with your experiment ID in the experiment root.
+
+- If you specify no options the resulting experiment will be configured the way that suite is run in the tier 1 testing.
+
+- If you want to be taken through all the questions for configuring the experiment you would specify `swell create <suite> -m cli`
+

docs/examples/description.md

@@ -0,0 +1,99 @@
+## Introduction
+In this section, some practical examples for different suites (workflows) will be presented.
+
+It will be assumed that SWELL has already been installed and loaded as a module following the installation instructions. You can execute `swell --help` and `module list` to check if `swell` is loaded properly and commands work.
+
+## Creating an Experiment Directory
+
+There are common elements in these examples in terms of [creating](../creating_an_experiment.md) and [launching](../launching_an_experiment.md) experiments. We will take a closer look at the `experiment.yaml` that controls the different aspects of the JEDI configuration creations.
+
+
+### Using Defaults:
+To create a `3dvar` suite run the following command. This will use the default `3dvar-tier1` test configuration:
+
+```bash
+swell create 3dvar
+```
+This will create the experiment directory in the default `experiment_root` with the
+default `experiment_id`, which are currently:
+
+```yaml
+experiment_root: /discover/nobackup/{$USER}/SwellExperiments
+experiment_id: {suite_name}-suite
+```
+
+<details>
+  <summary> <strong> Advanced Tip:</strong> </summary>
+
+If you would like to create the experiment folder at a different location, you can use the override option (`-o` or `--override`):
+
+```bash
+swell create 3dvar -o override.yaml
+```
+
+The `override.yaml` should contain the following keys to override defaults:
+
+```yaml
+
+experiment_root: /discover/nobackup/{your_username}/different_folder
+experiment_id: test001
+```
+
+</details>
+
+### Using CLI (Questionary):
+
+Alternatively, you can use the CLI option to create your experiment folder:
+
+```bash
+swell create 3dvar -m cli
+```
+
+This will walk you through different options depending on the suite type which is very similar
+to `gcm_setup` method used within GEOSgcm.
+
+Either method (defaults with override or CLI) will
+
+
+
+## Experiment Directory:
+
+Inside the experiment folder, there will be multiple folders and subfolders. After launching an experiment,
+and as different tasks start running, there will be additional folders, however prior
+to launching there will be
+
+```bash
+{experiment_id}/
+├── configuration
+└── {experiment_id}-suite/
+    ├── eva/
+    ├── experiment.yaml
+    ├── flow.cylc
+    ├── modules
+    └── modules-csh
+```
+Let's breakdown these two folders here:
+
+**configuration:** This copies model, observations, and satellite channel information from the
+Swell source installation folder. Most users wouldn't change this unless some changes are required
+for modifying the configurations and parametrizations in JEDI applications. Even then, it is suggested
+to do these type of modifications by creating a seperate Swell branch and reinstalling Swell. Otherwise,
+they will likely get overwritten.
+
+**{experiment_id}-suite:**
+
+Contains suite (or workflow) specific files.
+
+`modules` and `modules-csh` are automatically generated and used by Cylc to load `spack-stack` modules,
+additonal installations (such as R2D2/EVA), and `$PATH` dependencies.
+
+`eva/`: contains batch processed EVA yamls that could be defined for each model. They are created at
+each cycle and currently have three different options: increments (in Model space), observations (in IODA space),
+and jedi_log, which is used to plot Cost functions by parsing JEDI log outputs.
+
+`flow.cylc`: (Users don't need to modify this) This is the Cylc workflow file that desribes task inner and inter
+dependencies. For each suite, this will have a different structure and different scripts/tasks within.
+
+`experiment.yaml`: This is the key configuration file that dictates the inputs for contain configuration variables that will be used for different scripts in the workflow.
+
+For each JEDI bundle type (i.e., fv3-jedi, soca) and suite (3dvar, hofx etc.) in this section, we will display the `experiment.yaml` and talk about details.