porting structure of old pdf documentation

README.md

@@ -1,2 +1,74 @@
 # CryoGridDocumentation
 Documentation of the Community version of CryoGrid
+
+
+## How to participate to the documentation
+
+There are two ways you can add to the documentation:
+1. if you are already a contributor then you can simply clone the main repository directly from https://github.com/CryoGrid/CryoGridDocumentation. 
+2. if you are **not** a contributor, then you can fork the repository, do the changes, and finally do a [Pull Request](https://www.thinkful.com/learn/github-pull-request-tutorial/) 
+
+If you want to request rights for contribution, please contact **XXXXXXXXX**
+
+## How to add content
+
+The documentation is written in markup language reStructuredText `.rst` or [Markdown](https://www.markdownguide.org/basic-syntax/)(`.md`). rST is the preferred markup language, but both are supported as argued in [this blog post](https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/).
+
+### Directly online
+This works if the CryoGrid Project Administrator have added you as a Contributor. Then you will have the possibility to edit directly the file contents on github
+
+### Via cloning and working remotely
+
+To develop and contribute to the documentation in the most effective way then there are again two ways. 
+1. you clone the [CryoGridDocumentation](https://github.com/CryoGrid/CryoGridDocumentation) to your computer, edit the files you want, commit your changes and push them to Github. **WARNING: The main drawback of this method is that the changes you made could brake the build of the documentation (conversion of `.rst` and `.md` files to `html`**
+2. you also clone the [CryoGridDocumentation](https://github.com/CryoGrid/CryoGridDocumentation) to your computer, but then you setup your computer with a Miniconda virtual environment.
+
+#### Steps to setup the Sphinx documentation environment
+1. install [Miniconda](https://docs.conda.io/en/latest/miniconda.html)`
+2. Then in your terminal (assuming you're on Linux or MacOS)
+```shell
+# if your setup with SSH on github:
+git clone git@github.com:CryoGrid/CryoGridDocumentation.git
+# otherwise:
+git clone https://github.com/CryoGrid/CryoGridDocumentation.git
+
+# creates a virtual environment
+conda create -n docu_env
+
+# Activate the virtual environment
+conda activate docu_env
+
+# install pip. Pip is a Python package installer
+conda env update -n docu_env --file environment.yml
+```
+
+#### Test building the documentation laclly
+```
+# go the documentation folder
+cd CryoGridDocumentation
+
+# build the documentation locally on your machine
+make html
+```
+If no error occured during the build then, open the file `_build/html/index.htm` with your browser. If you're happy with your changes, **commit and push** the project to the github documentation. readthedocs.org will build automatically the documentation with the changes you just pushed.
+
+#### Creating a new page
+
+```shell
+# create a directory called source that will contain all files
+mkdir source
+nano source/intro.md
+```
+Indicate **Sphinx** to seek for this new file by adding in the file `index.rst`:
+```rst
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   source/intro
+   source/ add here you next content. One file per page. 
+```
+
+
+

index.rst

@@ -10,7 +10,11 @@ Welcome to CryoGrid Community Model's documentation!
    :maxdepth: 3
    :caption: Contents:
 
-   source/intro
+   source/Quick start
+   source/CryoGrid code structure
+   source/Adding new modules and functionality to CryoGrid
+   source/Categories of CryoGrid classes
+   source/Detailed documentation
 
 
 Indices and tables

source/Adding new modules and functionality to CryoGrid.md

@@ -0,0 +1 @@
+# Adding new modules and functionality to CryoGrid

source/Categories of CryoGrid classes.md

@@ -0,0 +1 @@
+# Categories of CryoGrid classes

source/CryoGrid code structure.md

@@ -0,0 +1,11 @@
+# CryoGrid code structure
+
+## Folder structure
+The CryoGrid model code is contained in the folder “modules”, in which it is organized as follows:
+- `modules/TIER0`: base level: contains the basic class definitions for CryoGrid SUBSURFACE and INTERACTION classes. TIER0 does not contain functional CryoGrid classes.
+- `modules/TIER1`: library level: inherits from TIER0 base classes, contains classes comprising all functions related to a certain physical process. TIER1 does not contain functional CryoGrid classes.
+- `modules/TIER2`: first SUBSURFACE class level: inherits from TIER1 library classes, contains fully functional CryoGrid classes
+- `modules/TIER3`: second SUBSURFACE class level: inherits from TIER2 SUBSURFACE classes, contains fully functional CryoGrid classes. TIER3 in particular contains the SUBSURFACE classes (GROUND, LAKE, etc. classes) that can interact with a (SUBSURFACE) SNOW class.
+- `modulesTIERXX/INTERACTION`: INTERACTION (IA) classes defining interactions and fluxes between pairs of SUBSURFACE classes, same TIER structure as for SUBSURFACE classes
+
+and so on ....

source/Detailed documentation.md

@@ -0,0 +1 @@
+# Detailed documentation

source/Quick start.md

@@ -0,0 +1,14 @@
+# Quick Start
+
+## Software requirements
+CryoGrid is written in [Matlab](https://www.mathworks.com/products/matlab.html). Version 2018x or higher is required.
+
+## Known Limitations
+Multi-tile (3D) functionality not yet implemented.
+
+## Quick start -model structure
+CryoGrid is a simulation tool to calculate ground temperatures and volumetric water/ice contents (as well as salt concentration, etc. depending on the selected `SUBSURFACE` classes) in single-tile (1D) stratigraphies. Multi-tile (3D) models can be realized by coupling several 1D stratigraphies.
+
+A stratigraphy is realized by stacking one or several `SUBSURFACE` classes, which each account for different physical processes. The different SUBSURFACE classes typically have specific state variables and model parameters and use different constitutive equations to calculate those variables.
+
+And so on ...